Aqua Basis

The AqToggle component is a minimalist switch from the for toggling Boolean states. Supports optional labels, help text, and disabled states. Emits standard events for easy integration with forms and frameworks.

<aq-toggle value="true">
	<div slot="on">ON</div>
	<div slot="off">OFF</div>
</aq-toggle>

Props and Attributes

Prop / Attr	Type	Default	Description
`value`	`boolean`	`false`	Current status of the toggle (on/off). It is mutable to allow internal or external control.
`isDisabled`	`boolean`	`false`	Disable interaction with the toggle.
`hasLabel`	`boolean`	`false`	It displays a label on the right with the switch current status: `on
`helperText`	`string`	`''`	Helper text below the toggle.
`idToggle`	`string`	`''`	Optional ID of the `<input>`. If not provided, one is generated automatically.

Internally, a uid (status) is generated withUniqueIdGenerator to ensure the label label ↔ input association.

PlayGround

You can interact with the component and experiment with its attributes and properties directly in this playground.

In the Code tab, the generated code snippet is available.

In addition to the interactive examples in this documentation, you can explore the full playground with all supported options and advanced configurations at the following link:

👉 Open full playground

https://aqua-ds-playground.masivianlabs.com/doc-storybook/index.html?path=/story/components-actions-aqtoggle--default&nav=0

<aside> ⚠️

Important: The code shown is in Web Component format. If you are using a specific framework (Vue, React, Angular), you must adapt it to the framework’s conventions before using it.

</aside>

Events

Event	Description	React	Angular	Vue	Vanilla
`input`	Emitted immediately upon switching.	`onInput={handleOnInput}`	`(onInput)="handleClick($event)"`	`@onInput="handleClick"`	`addEventListener('input', handler)`
`change`	Emitted after changing the status, useful for form submit handlers.	`onChange={handleChange}`	`(onChange)="handleChange($event)"`	`@onChange="handleChange"`	`addEventListener('change', handler)`

Event Types

Event	React	Angular	Vue
`input`	`(e:React.ChangeEvent<HTMLAqToggleElement>)`	`(e:Event)`	`(e:Event)`
`change`	`(e:React.ChangeEvent<HTMLAqToggleElement>)`	`(e:Event)`	`(e:Event)`

Slots

Slot	Fallback	Descripción
`on`	`On`	Text when `value = true` Displayed if `hasLabel` is `true`.
`off`	`Off`	Text when `value = false` . Displayed if `hasLabel` is `true`.

Binding Support by Framework

Framework	Two-Way Binding Support	Example	Notes
Vue 3	✅ `v-model`	`v-model="toggleValue"`	Works with `ref` binding and emits updates
Angular	✅ `[(ngModel)]`	`[(ngModel)]="toggleValue”`	Requires FormsModule or standalone setup
React	⚠️ Manual
Web Components	⚠️ Manual

In Frameworks

Props considerations

When using the components across different frameworks, keep in mind the convention for defining props:

In Vue, Angular and in vanilla JavaScript/HTML (direct Web Component usage), props must be written in kebab-case (e.g., is-required, helper-text).
In React props should be written in camelCase (e.g., isRequired, helperText).

This difference exists because each framework has its own best practices: React follows JavaScript conventions and uses camelCase for props, while Vue, Angular, and direct HTML/Web Components usage rely on kebab-case in templates to align with HTML attribute naming conventions.

Web Components

<aq-toggle value="true" has-label id-toggle="toggle-11" id="toggle-11">
  <div slot="on">Prendido</div>
  <div slot="off">Apagado</div>
</aq-toggle>
<script>
  const toggleTest = document.getElementById('toggle-11');
  toggleTest.addEventListener('input', (e) => {
    console.log('input', e.detail);
  });
  toggleTest.addEventListener('change', (e) => {
    console.log('change', e.detail);
  });
</script>

Vue

<script lang="ts">
  import { AqToggle } from '@aqua-ds/vue';
  import { defineComponent, ref } from 'vue';

  export default defineComponent({
    components: {
      AqToggle,
    },
    setup() {
      const toggleValue = ref(false);
      return {
        toggleValue,
      };
    },
  });
</script>

<template>
  <aq-toggle
    v-model="toggleValue"
    has-label
    helper-text="This is a toggle with custom labels"
  >
    <div slot="on"><span>Toggled on</span></div>
    <div slot="off"><span>Toggled off</span></div>
  </aq-toggle>
</template>