AisToggle

AisToggle represents a switch that can be either "on" or "off". Toggling a user preference such as dark mode is a familiar use. In general, toggle switches should provide immediate results. AisToggle is built with BaseToggle, which can be used to accommodate more specific use cases.

Props

v-model

v-model will bind a boolean to the switch. When the switch is "on", the boolean value will be true. v-model uses the modelValue prop under the covers. See Vue's documentation for details.

Enabled: true

<script setup>
  import {ref} from 'vue'
  import { AisToggle } from '@ais-public/ais-components'
  const enabled = ref(true)
</script>

<template>
  <div class="grid gap-4">
    <AisToggle v-model="enabled" label="Toggle example" sr-label />
    <div class="bg-ui-gray-50 border p-4">
      Enabled: {{enabled}}
    </div>
  </div>
</template>

label

label is a required prop that specifies the text label to be associated with the toggle switch. Every switch should have a label to make sure it is accessible to the widest audience. If you do not want to visually render a label, use the srLabel prop to make it visible only to screen readers.

Mobile messaging

<script setup>
import {ref} from 'vue'
import {AisToggle} from '@ais-public/ais-components'
const enabled = ref(true)
</script>

<template>
  <AisToggle
    v-model="enabled"
    label="Mobile messaging"
  />
</template>

srLabel

srLabel is a boolean prop. When provided the toggle's label is only visible to screen readers. See the first example to see it in use.

description

Set a brief description that appears alongside the toggle's label.

Mobile messagingContact via mobile phone

<script setup>
import {ref} from 'vue'
import {AisToggle} from '@ais-public/ais-components'
const enabled = ref(true)
</script>

<template>
  <AisToggle
    v-model="enabled"
    label="Mobile messaging"
    description="Contact via mobile phone"
  />
</template>

icon

AisToggle accepts an icon prop to display an icon alongside the switch. icon will accept either a FontAwesome icon definition or a string for one of our standard icons.

Mobile messagingContact via mobile phone

<script setup>
import {ref} from 'vue'
import {AisToggle} from '@ais-public/ais-components'
import { faMobileScreen } from '@fortawesome/free-solid-svg-icons'
import { library } from '@fortawesome/fontawesome-svg-core'

const enabled = ref(true)
library.add(faMobileScreen)
</script>

<template>
  <AisToggle
      v-model="enabled"
      :icon="faMobileScreen"
      label="Mobile messaging"
      description="Contact via mobile phone"
  />
</template>

inline

inline is a boolean prop. When present, the label and description will render on a single line.

Mobile messaging(Contact via mobile phone)

<script setup>
import {ref} from 'vue'
import {AisToggle} from '@ais-public/ais-components'
import { faMobileScreen } from '@fortawesome/free-solid-svg-icons'
import { library } from '@fortawesome/fontawesome-svg-core'

const enabled = ref(true)
library.add(faMobileScreen)
</script>

<template>
  <AisToggle inline
      v-model="enabled"
      :icon="faMobileScreen"
      label="Mobile messaging"
      description="(Contact via mobile phone)"
      size="lg"
  />
</template>

size

size controls the switch size. Accepted values are sm, md, and lg. The default value is md.

Mobile messagingContact via mobile phone

sm

md

lg

<script setup>
import {ref} from 'vue'
import {AisToggle} from '@ais-public/ais-components'
import {AisRadioGroup} from '@ais-public/ais-components'
import { faMobileScreen } from '@fortawesome/free-solid-svg-icons'
import { library } from '@fortawesome/fontawesome-svg-core'

const enabled = ref(true)
const size = ref('md')
library.add(faMobileScreen)
</script>

<template>
  <div class="grid gap-4">
    <AisToggle
        v-model="enabled"
        :icon="faMobileScreen"
        label="Mobile messaging"
        description="Contact via mobile phone"
        :size="size"
    />

    <AisRadioGroup
        class="bg-ui-gray-50 border p-4"
        v-model="size"
        :options="['sm', 'md', 'lg']" />
  </div>
</template>

disabled

The disabled prop will disable the toggle switch.

Mobile messagingContact via mobile phone

<script setup>
import {ref} from 'vue'
import {AisToggle} from '@ais-public/ais-components'
import { faMobileScreen } from '@fortawesome/free-solid-svg-icons'
import { library } from '@fortawesome/fontawesome-svg-core'

const enabled = ref(true)
library.add(faMobileScreen)
</script>

<template>
  <AisToggle disabled
      v-model="enabled"
      :icon="faMobileScreen"
      label="Mobile messaging"
      description="Contact via mobile phone"
  />
</template>

rounded

rounded is a boolean prop. When set to true, it will set the underlying BaseToggle to rounded="full". For consistency's sake, we want developers to use only these two corner variants.

Mobile messagingContact via mobile phone

<script setup>
import {ref} from 'vue'
import {AisToggle} from '@ais-public/ais-components'
import { faMobileScreen } from '@fortawesome/free-solid-svg-icons'
import { library } from '@fortawesome/fontawesome-svg-core'

const enabled = ref(true)
library.add(faMobileScreen)
</script>

<template>
  <AisToggle rounded
    v-model="enabled"
    :icon="faMobileScreen"
    label="Mobile messaging"
    description="Contact via mobile phone"
  />
</template>

name

If you add the name prop to a toggle, a hidden input element will be rendered and kept in sync with the switch state.

Events

update:modelValue

AisToggle uses Vue's standard v-model configuration. As a result, it will fire the @update:modelValue event whenever the toggle's value changes. Typically, v-model should be preferred, but binding the event directly may be useful in special circumstances. See Vue's documentation for details.