Switch

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


Installation

npx nextui-cli@latest add switch
The above command is for individual installation only. You may skip this step 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

AttributeTypeDescriptionDefault
childrenReactNodeThe label of the switch.-
valuestringThe value of the input element, used when submitting an HTML form.-
namestringThe name of the input element, used when submitting an HTML form.-
sizesm | md | lgThe size of the switch.md
colordefault | primary | secondary | success | warning | dangerThe color of the switch.primary
thumbIconThumbIconPropsThe icon to be displayed when the switch is checked.-
startContentReactNodeThe icon to be displayed at the start of the switch.-
endContentReactNodeThe icon to be displayed at the end of the switch.-
isSelectedbooleanWhether the element should be selected (controlled).-
defaultSelectedbooleanWhether the element should be selected (uncontrolled).-
isRequiredbooleanWhether user input is required on the input before form submission.false
isReadOnlybooleanWhether the input can be selected but not changed by the user.-
isDisabledbooleanWhether the switch is disabled.false
disableAnimationbooleanWhether the animation should be disabled.false
classNamesRecord<"base"| "wrapper"| "thumb"| "label" | "startContent" | "endContent" | "thumbIcon" , string>Allows to set custom class names for the switch slots.-

Switch Events

AttributeTypeDescription
onChangeReact.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) => voidHandler 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);