Toggle
Toggles are used to switch between two states, such as on/off or enabled/disabled. They are commonly used in settings, preferences, and other interactive elements. Click the interactive toggle preview below to test its state changes.
Loading Code Block...Full example
Section titled “Full example”Loading Code Block...Controlled state
Section titled “Controlled state”Pass checked and onChange for a controlled toggle. onChange receives the native change event; use event.target.checked for the new value. Omit checked to run in uncontrolled mode with internal state.
Use v-model (or v-model:modelValue) with a boolean ref. For toggle groups, bind an array ref and set value on each toggle so inclusion in the array represents the on-state.
Loading Code Block...Adjust the size prop to render the toggle as sm or md.
Loading Code Block...Title and subtext
Section titled “Title and subtext”title is the primary label rendered next to the track. subtext adds supporting copy. titleBold (default true) controls emphasis on the title.
Optional slots #title and #subtext replace the string props when you need rich markup.
Loading Code Block...Alignment
Section titled “Alignment”Use alignment to place the toggle left or right of the label stack.
Loading Code Block...Stretch (full width)
Section titled “Stretch (full width)”Use stretch so the label row spans its container with space distributed between the toggle and the label (useful in settings rows). The prop has the same name and semantics in both frameworks.
Loading Code Block...Toggle Disabled
Section titled “Toggle Disabled”Set the disabled prop to prevent user interaction. The demo below demonstrates both unchecked and checked disabled states.
Loading Code Block...Horizontal layout
Section titled “Horizontal layout”Use the textLayout="horizontal" prop to render the title inline next to the toggle with the subtext on the far side. This is useful for compact settings rows where the toggle should sit alongside its label rather than below it.
Loading Code Block...Props and API
Section titled “Props and API”Native attributes (name, id, value, data-*, etc.) are spread onto the hidden input via rest props.
Emits: update:modelValue — the new boolean (or, in toggle-group mode, the updated array of selected values).
Slots: #title, #subtext — take precedence over the matching string props when supplied.
Accessibility
Section titled “Accessibility”- The component renders a real
<input type="checkbox" class="sr-only">inside the outer<label>, so AT picks up the input’s role andcheckedstate natively. Clicking the label or hittingSpacewhile it is focused toggles the input. - The
titleprop becomes the visible label text inside the same<label>element, associating the copy with the control without needing explicitfor/idwiring. - The visible track and thumb are presentational; on-state and off-state are signalled both by the position of the thumb and by the track background colour.