Switch

Toggle switch component for boolean on/off states in editor toolbars, settings panels, and property inspectors. More space-efficient than a Checkbox for toggle options like “Show Grid”, “Snap to Grid”, or “Auto-Save”.

Live Preview

Import

import { Switch } from 'entangle-ui';

Usage

<Switch label="Show Grid" />

Controlled

Use checked and onChange for controlled mode. The onChange callback receives the new boolean value directly.

const [enabled, setEnabled] = useState(false);

<Switch checked={enabled} onChange={setEnabled} label="Auto-save" />;

Sizes

<Switch size="sm" label="Small (28x14px track)" />
<Switch size="md" label="Medium (34x18px track)" />
<Switch size="lg" label="Large (42x22px track)" />

| Size | Track | Thumb | Use case | | ---- | ------- | ----- | ------------------ | | sm | 28x14px | 10px | Compact toolbars | | md | 34x18px | 14px | Standard panels | | lg | 42x22px | 18px | Prominent settings |

Label Position

The label can be placed on either side of the switch.

<Switch label="Label on right" labelPosition="right" />
<Switch label="Label on left" labelPosition="left" />

Helper Text and Error

Display helper text below the switch, or an error message when validation fails.

<Switch
  label="Auto-save"
  helperText="Saves your work every 30 seconds"
/>

<Switch
  label="Enable feature"
  error
  errorMessage="This feature requires a premium plan"
/>

Disabled

<Switch disabled label="Disabled off" />
<Switch disabled checked label="Disabled on" />

Form Submission

Use the name prop for form integration. A hidden input is rendered with the value "on" when checked.

<Switch name="autoSave" label="Auto-save" />

Combining Props

<Switch
  checked={showGrid}
  onChange={setShowGrid}
  label="Show Grid"
  size="sm"
  labelPosition="left"
  helperText="Display grid overlay in viewport"
/>

Props

Prop	Type	Default	Description
checked	boolean	—	Whether the switch is on (controlled mode).
defaultChecked	boolean	false	Default on/off state (uncontrolled mode).
label	string	—	Switch label text.
labelPosition	'left' | 'right'	'right'	Position of the label relative to the switch.
size	'sm' | 'md' | 'lg'	'md'	Switch size controlling track and thumb dimensions.
disabled	boolean	false	Whether the switch is disabled.
helperText	string	—	Helper text displayed below the switch.
error	boolean	false	Whether the switch has an error state.
errorMessage	string	—	Error message displayed when error is true. Replaces helperText.
name	string	—	Name attribute for form submission.
onChange	(checked: boolean) => void	—	Change event handler receiving the new on/off state.
className	string	—	Additional CSS class names.
style	CSSProperties	—	Inline styles.
testId	string	—	Test identifier for automated testing.
ref	Ref<HTMLButtonElement>	—	Ref to the underlying button element.

The component also accepts all standard HTML <button> attributes (except onChange).

Accessibility

• Uses role="switch" on a native <button> element
• aria-checked reflects the current on/off state
• aria-disabled is set when the switch is disabled
• Helper text and error messages are linked via aria-describedby
• Label is rendered as a <label> element wrapping the switch for click target expansion
• Keyboard accessible: Space/Enter to toggle, Tab to navigate