Switch
A mechanical toggle switch built on reka-ui's Switch primitive, featuring 3D tactile keycaps, stamped guide track recesses, and industrial status markings, with v-model support.
Demo
基础 3D 机械滑块
工控通断铭牌刻印 (showLabels) & 吸合音效
机械形态 (shape="rocker")
尺寸矩阵 (sm / default / lg)
Installation
pnpm dlx brutx-vue@latest add switchUsage
<script setup>
import { ref } from 'vue'
import { Switch, Label } from 'brutx-ui-vue'
const enabled = ref(false)
</script>
<template>
<div class="flex items-center gap-3">
<Switch v-model="enabled" />
<Label>Airplane mode</Label>
</div>
</template>Industrial Marking Labels (I / O Marks)
Enable showLabels to render high-contrast monospace industrial markings (I / O) inside the track. Marked with aria-hidden for zero screen reader clutter.
<script setup>
import { ref } from 'vue'
import { Switch, Label } from 'brutx-ui-vue'
const power = ref(true)
</script>
<template>
<div class="flex items-center gap-3">
<Switch v-model="power" show-labels />
<Label>Main Equipment Power</Label>
</div>
</template>Mechanical Shape
Supports standard mechanical slider and industrial rocker switch shapes, orthogonally decoupled from the color variant.
<script setup>
import { ref } from 'vue'
import { Switch } from 'brutx-ui-vue'
const val1 = ref(false)
const val2 = ref(true)
</script>
<template>
<div class="flex items-center gap-4">
<Switch v-model="val1" shape="slider" variant="primary" />
<Switch v-model="val2" shape="rocker" variant="accent" show-labels />
</div>
</template>Disabled State
<template>
<Switch disabled />
</template>Custom Accessibility Label
Switch provides aria-label via locale by default, ensuring screen readers can read it correctly. When a more specific description is needed, customize it through the ariaLabel prop. Falls back to t('switch.toggle') when not provided.
<script setup>
import { ref } from 'vue'
import { Switch, Label } from 'brutx-ui-vue'
const sync = ref(false)
</script>
<template>
<div class="flex items-center gap-3">
<Switch v-model="sync" aria-label="Auto-sync data" />
<Label>Auto sync</Label>
</div>
</template>API Reference
| Name | Type | Default | Description |
|---|---|---|---|
class | string | undefined | undefined | CSS classes added to the Switch primitive root element. |
DetailsDeclared typestring | undefined Default value details
Sourcepackages/ui/src/components/switch/Switch.vue | |||
modelValueNullable | boolean | null | undefined | undefined | The controlled switch state, bound with v-model; null is treated as off. |
DetailsDeclared typeboolean | null | undefined Literal values
Default value details
Sourcepackages/ui/src/components/switch/Switch.vue | |||
defaultValue | boolean | undefined | undefined | The initial state used when modelValue is omitted; it takes precedence over defaultChecked when both are provided. |
DetailsDeclared typeboolean | undefined Literal values
Default value details
Sourcepackages/ui/src/components/switch/Switch.vue | |||
defaultChecked | boolean | undefined | undefined | An alias for the initial state in uncontrolled mode; overridden when defaultValue is also provided. |
DetailsDeclared typeboolean | undefined Literal values
Default value details
Sourcepackages/ui/src/components/switch/Switch.vue | |||
disabled | boolean | undefined | false | Disables switch interaction. |
DetailsDeclared typeboolean | undefined Literal values
Default value details
Sourcepackages/ui/src/components/switch/Switch.vue | |||
variant | "accent" | "danger" | "default" | "primary" | "secondary" | undefined | "default" | Sets the switch color and state style variant. |
DetailsDeclared typeNonNullable<"default" | "primary" | "secondary" | "danger" | "accent" | null | undefined> | undefined Literal values
Default value details
Sourcepackages/ui/src/components/switch/Switch.vue | |||
shape | "rocker" | "slider" | undefined | "slider" | Sets the mechanical appearance to a sliding or rocker-style switch. |
DetailsDeclared typeNonNullable<"slider" | "rocker" | null | undefined> | undefined Literal values
Default value details
Sourcepackages/ui/src/components/switch/Switch.vue | |||
size | "default" | "lg" | "sm" | undefined | "default" | Sets the size of the switch track and thumb. |
DetailsDeclared typeNonNullable<"default" | "lg" | "sm" | null | undefined> | undefined Literal values
Default value details
Sourcepackages/ui/src/components/switch/Switch.vue | |||
showLabels | boolean | undefined | false | Shows O/I markings for off and on inside the track; the markings are decorative and hidden from the accessibility tree. |
DetailsDeclared typeboolean | undefined Literal values
Default value details
Sourcepackages/ui/src/components/switch/Switch.vue | |||
ariaLabel | string | undefined | undefined | Sets the switch’s accessible name; the current locale’s default text is used when omitted. |
DetailsDeclared typestring | undefined Default value details
Sourcepackages/ui/src/components/switch/Switch.vue | |||
sound | boolean | undefined | false | Explicitly enables the relay sound when the state changes; sound is off by default. |
DetailsDeclared typeboolean | undefined Literal values
Default value details
Sourcepackages/ui/src/components/switch/Switch.vue | |||
| Name | Signature or type | Description |
|---|---|---|
@update:modelValue | [value: boolean] | Emits the new boolean after the user toggles the switch to synchronize v-model. |
DetailsDeclared type[value: boolean] Literal values
Sourcepackages/ui/src/components/switch/Switch.vue | ||
Accessibility
- Keyboard: Supports
Space/Enterto toggle switch state - ARIA attributes: Automatically manages
role="switch"andaria-checked; providesaria-labelvia locale by default - Focus management: Focusable via Tab key, uses
--brutal-ringtoken for visible focus ring - Label isolation:
showLabelsmarkings carryaria-hidden="true", preventing screen reader pollution