Switch
Used for toggling between two opposing states, such as "On/Off".
Basic Usage
Bind v-model to a Boolean variable.
Size
Use the size property to set the dimensions of the Switch.
Text Description
Use the active-text and inactive-text properties to set textual labels. Use inline-prompt to display the text inside the sliding handle area.
Custom Icons
Use the active-icon and inactive-icon properties to add icons. Use inline-prompt to place icons inside the sliding handle area.
Extended Value Types
You can set active-value and inactive-value properties, which accept Boolean, String, or Number types.
Disabled State
Set the disabled property to true to disable interaction.
Loading State
Set the loading property to true to display a loading spinner.
Prevent Toggling
Use the before-change property. If it returns false or a Promise that rejects, the switch state will not change.
Custom Action Icons
Use active-action-icon and inactive-action-icon to customize the icons inside the sliding handle (action point).
Usage in Nuxt
The Switch component fully supports Nuxt 3/4 SSR. When used in a Nuxt project, it is auto-imported.
SSR Considerations:
- ✅ Basic switch state and sizing styles are fully supported.
- ✅ Text descriptions and icons render consistently during SSR.
- ✅ Extended Value types (
active-value) are supported. - ⚠️ Initial state remains consistent with client-side hydration after SSR.
SSR Safety
The Switch component is deeply optimized for SSR, ensuring that handle positions and colors are correctly calculated during server-side rendering for a fluid visual experience.
API
Props
| Name | Description | Type | Default |
|---|---|---|---|
| model-value / v-model | Binding value; must equal active-value or inactive-value. | boolean | string | number | false |
| disabled | Whether to disable the switch | boolean | false |
| loading | Whether to show loading state | boolean | false |
| size | Switch size | 'large' | 'default' | 'small' | 'default' |
| width | Switch total width | number | string | — |
| inline-prompt | Whether to show icons/text inside the handle (max 3 chars) | boolean | false |
| active-icon | Icon displayed when status is ON (ignores active-text) | string | Component | — |
| inactive-icon | Icon displayed when status is OFF (ignores inactive-text) | string | Component | — |
| active-action-icon | Icon displayed inside the sliding handle when ON | string | Component | — |
| inactive-action-icon | Icon displayed inside the sliding handle when OFF | string | Component | — |
| active-text | Text displayed when switch is ON | string | — |
| inactive-text | Text displayed when switch is OFF | string | — |
| active-value | Value when status is ON | boolean | string | number | true |
| inactive-value | Value when status is OFF | boolean | string | number | false |
| name | Form name attribute | string | — |
| validate-event | Whether to trigger form validation on change | boolean | true |
| before-change | Hook before toggle; returning false or rejecting stops toggle | () => Promise<boolean> | boolean | — |
| id | Input ID | string | — |
| tabindex | Input tabindex | string | number | — |
| aria-label | Native input aria-label equivalent | string | — |
Events
| Name | Description | Parameters |
|---|---|---|
| change | Callback function when switch state changes | (value: boolean | string | number) => void |
Slots
| Name | Description |
|---|---|
| active-action | Custom content for the sliding handle (Action) when ON |
| inactive-action | Custom content for the sliding handle (Action) when OFF |
| active | Custom content when ON (inside handle if inline-prompt, else right side) |
| inactive | Custom content when OFF (inside handle if inline-prompt, else left side) |
Expose
| Name | Description | Type |
|---|---|---|
| focus | Focus the Switch | () => void |
| checked | Whether the Switch is currently active | ComputedRef<boolean> |
Theme Variables
| Variable | Description | Default |
|---|---|---|
--yh-switch-on-color | Background color when active | var(--yh-color-primary) |
--yh-switch-off-color | Background color when inactive | var(--yh-border-color) |
--yh-switch-width | Total switch width | 40px |
--yh-switch-height | Total switch height | 20px |
--yh-switch-button-size | Sliding handle size | 16px |
--yh-switch-font-size | Font size | var(--yh-font-size-base) |