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-partattribute 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
asChildproperty, make sure that thelabelelement is the direct child of theSwitch.Rootcomponent.
Examples
Learn how to use the Switch component in your project. Let’s take a look at
the most basic example:
import { Switch } from '@ark-ui/react'
export const Basic = () => (
<Switch.Root>
<Switch.Control>
<Switch.Thumb />
</Switch.Control>
<Switch.Label>Label</Switch.Label>
</Switch.Root>
)
import { Switch } from '@ark-ui/solid'
export const Basic = () => (
<Switch.Root>
<Switch.Control>
<Switch.Thumb />
</Switch.Control>
<Switch.Label>Label</Switch.Label>
</Switch.Root>
)
<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.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:
import { useState } from 'react'
import { Switch } from '@ark-ui/react'
export const Controlled = () => {
const [checked, setChecked] = useState(false)
return (
<Switch.Root checked={checked} onCheckedChange={(e) => setChecked(e.checked)}>
<Switch.Control>
<Switch.Thumb />
</Switch.Control>
<Switch.Label>Label</Switch.Label>
</Switch.Root>
)
}
import { createSignal } from 'solid-js'
import { Switch } from '@ark-ui/solid'
export const Controlled = () => {
const [checked, setChecked] = createSignal(false)
return (
<Switch.Root checked={checked()} onCheckedChange={(e) => setChecked(e.checked)}>
<Switch.Control>
<Switch.Thumb />
</Switch.Control>
<Switch.Label>Label</Switch.Label>
</Switch.Root>
)
}
<script setup lang="ts">
import { ref } from 'vue'
import { Switch } from '@ark-ui/vue'
const checked = ref(false)
</script>
<template>
<Switch.Root v-model="checked">
<Switch.Control>
<Switch.Thumb />
</Switch.Control>
<Switch.Label>Label</Switch.Label>
</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:
Story not foundStory not foundStory not foundAPI Reference
Root
| Prop | Type | Default |
|---|---|---|
asChildRender as a different element type. | boolean | |
checkedWhether the switch is checked. | boolean | |
defaultCheckedThe initial checked state of the switch. | boolean | |
disabledWhether the switch is disabled. | boolean | |
formThe id of the form that the switch belongs to | string | |
idThe unique identifier of the machine. | string | |
idsThe ids of the elements in the switch. Useful for composition. | Partial<{
root: string
input: string
control: string
label: string
thumb: string
}> | |
invalidIf `true`, the switch is marked as invalid. | boolean | |
labelSpecifies the localized strings that identifies the accessibility elements and their states | string | |
nameThe name of the input field in a switch
(Useful for form submission). | string | |
onCheckedChangeFunction to call when the switch is clicked. | (details: CheckedChangeDetails) => void | |
readOnlyWhether the switch is read-only | boolean | |
requiredIf `true`, the switch input is marked as required, | boolean | |
valueThe value of switch input. Useful for form submission. | string | number | "on" |
Control
| Prop | Type | Default |
|---|---|---|
asChildRender as a different element type. | boolean |
Label
| Prop | Type | Default |
|---|---|---|
asChildRender as a different element type. | boolean |
Thumb
| Prop | Type | Default |
|---|---|---|
asChildRender as a different element type. | boolean |