Switch

The Switch component is used as an alternative between checked and not checked states.

Storybook @nextui-org/switch React Aria Source Styles source

Installation

npx nextui-cli@latest add switch

No need to install this package if @nextui-org/react is already installed globally.

Import

Usage

With Label

Disabled

Sizes

Colors

With Thumb Icon

With Icons

You can also add icons to start and end of the switch by using startContent and endContent props.

Controlled

Note: NextUI Switch also supports native events like onChange, useful for form libraries such as Formik and React Hook Form.

Slots

base: Base slot for the switch. It is the main wrapper.
wrapper: The wrapper of the start icon, end icon and thumb.
thumb: The thumb element of the switch. It is the circle element.
label: The label slot of the switch.
startContent: The icon slot at the start of the switch.
endContent: The icon slot at the end of the switch.
thumbIcon: The icon slot inside the thumb.

Custom Styles

You can customize the Switch component by passing custom Tailwind CSS classes to the component slots.

Custom Implementation

In case you need to customize the switch even further, you can use the useSwitch hook to create your own implementation.

Data Attributes

Switch has the following attributes on the base element:

data-selected: When the switch is checked. Based on isSelected prop.
data-pressed: When the switch is pressed. Based on usePress
data-readonly: When the switch is readonly. Based on isReadOnly prop.
data-hover: When the switch is being hovered. Based on useHover
data-focus: When the switch is being focused. Based on useFocusRing.
data-focus-visible: When the switch is being focused with the keyboard. Based on useFocusRing.
data-disabled: When the switch is disabled. Based on isDisabled prop.

Accessibility

Built with a native HTML <input> element.
Full support for browser features like form autofill.
Keyboard focus management and cross browser normalization.
Keyboard event support for Tab and Space keys.
Labeling support for assistive technology.
Exposed as a switch to assistive technology via ARIA

API

Switch Props

Attribute	Type	Description	Default
children	`ReactNode`	The label of the switch.	-
value	`string`	The value of the input element, used when submitting an HTML form.	-
name	`string`	The name of the input element, used when submitting an HTML form.	-
size	`sm` \| `md` \| `lg`	The size of the switch.	`md`
color	`default` \| `primary` \| `secondary` \| `success` \| `warning` \| `danger`	The color of the switch.	`primary`
thumbIcon	ThumbIconProps	The icon to be displayed when the switch is checked.	-
startContent	`ReactNode`	The icon to be displayed at the start of the switch.	-
endContent	`ReactNode`	The icon to be displayed at the end of the switch.	-
isSelected	`boolean`	Whether the element should be selected (controlled).	-
defaultSelected	`boolean`	Whether the element should be selected (uncontrolled).	-
isRequired	`boolean`	Whether user input is required on the input before form submission.	`false`
isReadOnly	`boolean`	Whether the input can be selected but not changed by the user.	-
isDisabled	`boolean`	Whether the switch is disabled.	`false`
disableAnimation	`boolean`	Whether the animation should be disabled.	`false`
classNames	`Record<"base"｜ "wrapper"｜ "thumb"｜ "label" ｜ "startContent" ｜ "endContent" ｜ "thumbIcon" , string>`	Allows to set custom class names for the switch slots.	-

Switch Events

Attribute	Type	Description
onChange	`React.ChangeEvent<HTMLInputElement>`	Handler that is called when the element's selection state changes. You can pull out the new checked state by accessing `event.target.checked` (boolean).
onValueChange	`(isSelected: boolean) => void`	Handler that is called when the element's selection state changes.

Types

Switch Icon Props

type IconProps = {
  "data-checked": string;
  width: string;
  height: string;
  isSelected: boolean;
  className: string;
};

type CheckboxIconProps = ReactNode | ((props: IconProps) => ReactNode);