Skip to content

Switch ​

A toggle switch component for binary on/off states. Perfect for settings, feature toggles, and preferences. Built with accessibility in mind and fully customizable through CSS custom properties.

Colors ​

Six semantic colors for different contexts. Defaults to neutral when no color is specified.

Full width

Sizes ​

Three sizes for different contexts.

Full width

States ​

Checked ​

Toggle between on and off states.

Full width

Disabled ​

Prevent interaction and reduce opacity for unavailable options.

Full width

Usage Examples ​

Form Integration ​

Switches work seamlessly with forms using name and value attributes. Use switches for instant actions that take effect immediately, when changes require a save/submit action, use a checkbox instead.

Full width

Event Handling ​

Listen to change events for custom logic.

Full width

When to Use Switch vs Checkbox ​

Use Switch for:

  • Settings that take effect immediately
  • Enabling/disabling features
  • Toggling system states (on/off, true/false)

Use Checkbox for:

  • Form selections that require submit
  • Multiple selections in a list
  • Agreeing to terms and conditions

Framework Examples ​

React ​

tsx
import '@vielzeug/refine/switch';

function SettingsPanel() {
  const [notifications, setNotifications] = useState(true);

  return (
    <ore-switch checked={notifications} onChange={(e) => setNotifications(e.currentTarget.checked)}>
      Enable notifications
    </ore-switch>
  );
}

Vue ​

vue
<template>
  <ore-switch :checked="notifications" @change="notifications = $event.currentTarget.checked"> Enable notifications </ore-switch>
</template>

<script setup>
import { ref } from 'vue';
import '@vielzeug/refine/switch';

const notifications = ref(true);
</script>

Svelte ​

svelte
<script>
  import '@vielzeug/refine/switch';
  let notifications = true;
</script>

<ore-switch
  checked={notifications}
  on:change={(e) => notifications = e.currentTarget.checked}
>
  Enable notifications
</ore-switch>

API Reference ​

ore-switch

Attributes ​

AttributeTypeDefaultDescription
checkedbooleanfalseSwitch checked state
disabledbooleanfalseDisable the switch
color'primary' | 'secondary' | 'success' | 'warning' | 'error''primary'Semantic color
size'sm' | 'md' | 'lg''md'Switch size
namestring-Form field name
valuestring-Form field value when on

Slots ​

SlotDescription
(default)Switch label content

Events ​

EventDetailDescription
change{ checked: boolean, value: string | null, originalEvent: Event }Emitted when checked state changes

CSS Custom Properties ​

PropertyDescriptionDefault
--switch-widthTrack widthSize-dependent
--switch-heightTrack heightSize-dependent
--switch-track-bgInactive (unchecked) track backgroundTheme-dependent
--switch-checked-bgActive (checked) track backgroundColor-dependent
--switch-thumb-bgThumb background colorTheme-dependent
--switch-font-sizeLabel font sizeSize-dependent

Accessibility ​

The switch component follows WCAG 2.1 Level AA standards.

The component uses role="switch" with aria-checked reflecting the on/off state ("true" or "false"). aria-labelledby links the label; aria-describedby links helper and error text. aria-disabled reflects the disabled state. A minimum 44 × 44 px touch target is enforced for mobile usability.

Keyboard navigation is fully supported: Space and Enter toggle the switch, and Tab moves focus to and from the control. Always provide a visible text label: use clear labels that describe what the switch controls; if a switch must be icon-only, supply an aria-label so screen readers can announce the purpose.