Ark Logo

Switch

A control element that allows for a binary selection.

Anatomy

To set up the switch correctly, you'll need to understand its anatomy and how we name its parts.

Each part includes a data-part attribute to help identify them in the DOM.

Design impact on the asChild property

The Switch.Root element of the switch is a label element. This is because the switch is a form control and should be associated with a label to provide context and meaning to the user. Otherwise, the HTML and accessibility structure will be invalid.

If you need to use the asChild property, make sure that the label element is the direct child of the Switch.Root component.

Examples

Learn how to use the Switch component in your project. Let's take a look at the most basic example:

<script setup lang="ts">
import { Switch } from '@ark-ui/vue'
</script>

<template>
  <Switch.Root>
    <Switch.Control>
      <Switch.Thumb />
    </Switch.Control>
    <Switch.Label>Label</Switch.Label>
    <Switch.HiddenInput />
  </Switch.Root>
</template>

Controlled Switch

For a controlled Switch component, the state of the toggle is managed using the checked prop, and updates when the onCheckedChange event handler is called:

<script setup lang="ts">
import { ref } from 'vue'
import { Switch } from '@ark-ui/vue'

const checked = ref(true)
</script>

<template>
  <Switch.Root v-model:checked="checked">
    <Switch.Control>
      <Switch.Thumb />
    </Switch.Control>
    <Switch.Label>Label</Switch.Label>
    <Switch.HiddenInput />
  </Switch.Root>
</template>

Render Prop Usage

The Switch component also allows for a render prop, granting direct access to its internal state. This enables you to dynamically adjust and customize aspects of the component based on its current state:

<script setup lang="ts">
import { Switch } from '@ark-ui/vue'
</script>

<template>
  <Switch.Root>
    <Switch.Control>
      <Switch.Thumb />
    </Switch.Control>
    <Switch.Context v-slot="api">
      <Switch.Label>Feature is {{ api.checked ? 'enabled' : 'disabled' }}</Switch.Label>
    </Switch.Context>
    <Switch.HiddenInput />
  </Switch.Root>
</template>

API Reference

Root

PropDefaultType
asChildfalse
boolean

checked
boolean

Whether the switch is checked.

defaultChecked
boolean

The checked state of the switch when it is first rendered. Use this when you do not need to control the state of the switch.

disabled
boolean

Whether the switch is disabled.

form
string

The id of the form that the switch belongs to

id
string

The unique identifier of the machine.

ids
Partial<{ root: string input: string control: string label: string thumb: string }>

The ids of the elements in the switch. Useful for composition.

invalid
boolean

If `true`, the switch is marked as invalid.

label
string

Specifies the localized strings that identifies the accessibility elements and their states

name
string

The name of the input field in a switch (Useful for form submission).

readOnly
boolean

Whether the switch is read-only

required
boolean

If `true`, the switch input is marked as required,

value'on'
string | number

The value of switch input. Useful for form submission.

EmitEvent
checkedChange
[details: CheckedChangeDetails]

Function to call when the switch is clicked.

update:checked
[checked: boolean]

The callback fired when the model value changes.

Data AttributeValue
[data-active]Present when active or pressed
[data-focus]Present when focused
[data-readonly]Present when read-only
[data-hover]Present when hovered
[data-disabled]Present when disabled
[data-state]"checked" | "unchecked"
[data-invalid]Present when invalid

Control

PropDefaultType
asChildfalse
boolean

Data AttributeValue
[data-active]Present when active or pressed
[data-focus]Present when focused
[data-readonly]Present when read-only
[data-hover]Present when hovered
[data-disabled]Present when disabled
[data-state]"checked" | "unchecked"
[data-invalid]Present when invalid

HiddenInput

PropDefaultType
asChildfalse
boolean

Label

PropDefaultType
asChildfalse
boolean

Data AttributeValue
[data-active]Present when active or pressed
[data-focus]Present when focused
[data-readonly]Present when read-only
[data-hover]Present when hovered
[data-disabled]Present when disabled
[data-state]"checked" | "unchecked"
[data-invalid]Present when invalid

Thumb

PropDefaultType
asChildfalse
boolean

Data AttributeValue
[data-active]Present when active or pressed
[data-focus]Present when focused
[data-readonly]Present when read-only
[data-hover]Present when hovered
[data-disabled]Present when disabled
[data-state]"checked" | "unchecked"
[data-invalid]Present when invalid

Accessibility

Complies with the Switch WAI-ARIA design pattern.

Keyboard Support

KeyDescription
SpaceEnter
Toggle the switch