DocsComponents

Switch

Turn a setting on or off, with an immediate effect.

Do not disturb

Installation

Terminal

pnpm dlx shadcn@latest add https://react-toolbox.io/r/switch.json

New here? Set up your project first. Styles, fonts, and required components are included.

Usage

Keep checked in state and update it from onChange. Use a short label that describes the setting rather than the action.

Use the Code tab above for a complete example. The import follows your configured UI alias. See Theming to customize colors, spacing, and style slots.

State and callbacks

Switch is controlled: pass checked and update it with the boolean received by onChange. checked defaults to false; defaultChecked does not replace the controlled checked prop.

The callback receives the next boolean and the input click event. The ref exposes focus(), blur(), and inputElement.

API reference

Generated from the installed TypeScript source. Defaults are the values declared by each function; a dash means no parameter default is declared. Forwarded props can use the receiving component’s default. Callback types show the exact arguments passed to your handler.

`Switch`

Property	Type	Default
`label`	`React.ReactNode`	`—`
`ripple`	`boolean`	`—`
`classNames`	`SwitchTheme` Classes for the component's rendered parts. Applied after legacy theme overrides.	`—`
`theme`Deprecated alias	`SwitchTheme` Use classNames for style slots; use ThemeProvider for design tokens.	`—`
`ref`	`React.Ref<SwitchHandle>`	`—`

Callbacks

Property	Type	Default
`onMouseEnter`	`React.MouseEventHandler<HTMLLabelElement>`	`—`
`onMouseLeave`	`React.MouseEventHandler<HTMLLabelElement>`	`—`
`onChange`	`(checked: boolean, event: React.MouseEvent<HTMLInputElement>) => void`	`—`

Also inherits Omit<React.InputHTMLAttributes<HTMLInputElement>, 'onChange' | 'type' | 'size' | 'onMouseEnter' | 'onMouseLeave'>, except the omissions and overrides in its exported props type below. Use the supported native aria-*, data-*, event, and element attributes as appropriate.

Additional defaults on inherited props: checked = false; className = ''; disabled = false.

Style slots

Pass a map of Tailwind classes to classNames. Available keys:

disabled
field
input
off
on
ripple
switch-off
switch-on
text
thumb

theme is the deprecated compatibility alias. When both are provided, classNames wins conflicting utilities within each slot. See Theming for tokens and override rules.

Exported TypeScript types

Expand a type to inspect its full declaration, including generic constraints, union branches, callback arguments, ref handles, and inherited props. Import these types from @/components/ui/material/switch.

SwitchTheme

tsx

type SwitchTheme = Partial<
  Record<
    'disabled' | 'field' | 'input' | 'off' | 'on' | 'ripple' | 'switch-off' | 'switch-on' | 'text' | 'thumb',
    string
  >
>;

SwitchClassNames

tsx

type SwitchClassNames = SwitchTheme;

SwitchHandle

tsx

interface SwitchHandle {
  focus(): void;
  blur(): void;
  readonly inputElement: HTMLInputElement | null;
}

SwitchProps

tsx

interface SwitchProps
  extends Omit<
    React.InputHTMLAttributes<HTMLInputElement>,
    'onChange' | 'type' | 'size' | 'onMouseEnter' | 'onMouseLeave'
  > {
  label?: React.ReactNode;
  onMouseEnter?: React.MouseEventHandler<HTMLLabelElement>;
  onMouseLeave?: React.MouseEventHandler<HTMLLabelElement>;
  ripple?: boolean;
  /** Classes for the component's rendered parts. Applied after legacy theme overrides. */
  classNames?: SwitchTheme;
  /** @deprecated Use classNames for style slots; use ThemeProvider for design tokens. */
  theme?: SwitchTheme;
  ref?: React.Ref<SwitchHandle>;
  onChange?: (checked: boolean, event: React.MouseEvent<HTMLInputElement>) => void;
}

Material guidelines

Use a switch for a single setting with an immediate on/off effect. Describe the setting itself in its label.
Use checkboxes for independent selections in a set and radios for mutually exclusive choices.

Material Design 1: Selection controls