Switch

Turn a setting on or off immediately.

View component source ↗

Preview

Example

A minimal example to get started.

Enable notifications

Installation

Install this component and its dependencies in a project initialized with shadcn.

pnpm dlx shadcn@latest add https://ui.hyunjoon.net/r/switch.json

Usage

This is the basic example. Use the Code tab above for the selected example. Adjust import aliases to match your project.

import { Switch } from "@/components/ui/switch";

export default function Example() {
  return (
    <label className="flex items-center gap-3 text-sm">
      <Switch defaultChecked />
      Enable notifications
    </label>
  );
}

API reference

Derived from the installed component types. Native DOM props are also supported where applicable. A dash means no explicit default is documented. Some props depend on the selected mode.

Switch

Switch properties
Prop	Type	Default	Description
`id`	string \| undefined string \| undefined	`—`	The id of the switch element.
`checked`	boolean \| undefined boolean \| undefined	`—`	Whether the switch is currently active. To render an uncontrolled switch, use the `defaultChecked` prop instead.
`defaultChecked`	boolean \| undefined boolean \| undefined	`false`	Whether the switch is initially active. To render a controlled switch, use the `checked` prop instead.
`disabled`	boolean \| undefined boolean \| undefined	`false`	Whether the component should ignore user interaction.
`inputRef`	React.Ref<HTMLInputElement> \| undefined React.Ref<HTMLInputElement> \| undefined	`—`	A ref to access the hidden `<input>` element.
`name`	string \| undefined string \| undefined	`—`	Identifies the field when a form is submitted.
`form`	string \| undefined string \| undefined	`—`	Identifies the form that owns the hidden input. Useful when the switch is rendered outside the form.
`onCheckedChange`	((checked: boolean, eventDetails: SwitchPrimitive.Root.ChangeEventDetails) => void) \| unde… ((checked: boolean, eventDetails: SwitchPrimitive.Root.ChangeEventDetails) => void) \| undefined	`—`	Event handler called when the switch is activated or deactivated.
`readOnly`	boolean \| undefined boolean \| undefined	`false`	Whether the user should be unable to activate or deactivate the switch.
`required`	boolean \| undefined boolean \| undefined	`false`	Whether the user must activate the switch before submitting a form.
`value`	string \| undefined string \| undefined	`—`	The value submitted with the form when the switch is on. By default, switch submits the "on" value, matching native checkbox behavior.
`uncheckedValue`	string \| undefined string \| undefined	`—`	The value submitted with the form when the switch is off. By default, unchecked switches do not submit any value, matching native checkbox behavior.
`nativeButton`	boolean \| undefined boolean \| undefined	`false`	Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button.
`className`	string \| ((state: SwitchRootState) => string \| undefined) \| undefined string \| ((state: SwitchRootState) => string \| undefined) \| undefined	`—`	CSS class applied to the element, or a function that returns a class based on the component's state.
`style`	React.CSSProperties \| ((state: SwitchRootState) => React.CSSProperties \| undefined) \| unde… React.CSSProperties \| ((state: SwitchRootState) => React.CSSProperties \| undefined) \| undefined	`—`	Style applied to the element, or a function that returns a style object based on the component's state.
`ref`	React.Ref<HTMLSpanElement> \| undefined React.Ref<HTMLSpanElement> \| undefined	`—`	Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`onFocus`	((event: BaseUIEvent<React.FocusEvent<HTMLSpanElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.FocusEvent<HTMLSpanElement, Element>>) => void) \| undefined	`—`	Called when the control receives focus.
`onBlur`	((event: BaseUIEvent<React.FocusEvent<HTMLSpanElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.FocusEvent<HTMLSpanElement, Element>>) => void) \| undefined	`—`	Called when the control loses focus.
`onKeyDown`	((event: BaseUIEvent<React.KeyboardEvent<HTMLSpanElement>>) => void) \| undefined ((event: BaseUIEvent<React.KeyboardEvent<HTMLSpanElement>>) => void) \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	((event: BaseUIEvent<React.MouseEvent<HTMLSpanElement, MouseEvent>>) => void) \| undefined ((event: BaseUIEvent<React.MouseEvent<HTMLSpanElement, MouseEvent>>) => void) \| undefined	`—`	Called when the element is activated.
`render`	React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn… React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, SwitchRootState> \| undefined	`—`	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
`size`	"default" \| "sm" \| undefined "default" \| "sm" \| undefined	`"default"`	Visual size of the component.

Usage notes

Use a label that describes the setting itself. Prefer a checkbox when the choice is part of a form that needs explicit submission.