Switch

Import

import { Switch, SwitchGroup, Label } from '@heroui/react';

Usage

Enable notifications

import {Label, Switch} from "@heroui/react";

export function Basic() {
  return (
    <Switch>

Anatomy

Import the Switch component and access all parts using dot notation.

import { Switch, Label } from '@heroui/react';

export default () => (
  <Switch>
    <Switch.Control>
      <Switch.Thumb>
        <Switch.Icon/> {/* Optional */}
      </Switch.Thumb>
    </Switch.Control>
    <Label/> {/* Optional */}
  </Switch>
);

For grouping multiple switches, use the SwitchGroup component:

import { Switch, SwitchGroup, Label } from '@heroui/react';

export default () => (
  <SwitchGroup>
    <Switch>
      <Switch.Control>
        <Switch.Thumb />
      </Switch.Control>
      <Label>Option 1</Label>
    </Switch>
    <Switch>
      <Switch.Control>
        <Switch.Thumb />
      </Switch.Control>
      <Label>Option 2</Label>
    </Switch>
  </SwitchGroup>
);

Disabled

Enable notifications

import {Label, Switch} from "@heroui/react";

export function Disabled() {
  return (
    <Switch isDisabled>

Default Selected

Enable notifications

import {Label, Switch} from "@heroui/react";

export function DefaultSelected() {
  return (
    <Switch defaultSelected>

Controlled

Enable notifications

Switch is off

"use client";

import {Label, Switch} from "@heroui/react";
import React from "react";

Without Label

import {Switch} from "@heroui/react";

export function WithoutLabel() {
  return (
    <Switch aria-label="Enable notifications">

Sizes

SmallMediumLarge

import {Label, Switch} from "@heroui/react";

export function Sizes() {
  return (
    <div className="flex gap-6">

Label Position

Label afterLabel before

import {Label, Switch} from "@heroui/react";

export function LabelPosition() {
  return (
    <div className="flex flex-col gap-4">

With Icons

With Description

Public profileAllow others to see your profile information

import {Description, Label, Switch} from "@heroui/react";

export function WithDescription() {
  return (
    <div className="max-w-sm">

Group

Allow NotificationsMarketing emailsSocial media updates

import {Label, Switch, SwitchGroup} from "@heroui/react";

export function Group() {
  return (
    <SwitchGroup>

Group Horizontal

NotificationsMarketingSocial

import {Label, Switch, SwitchGroup} from "@heroui/react";

export function GroupHorizontal() {
  return (
    <SwitchGroup className="overflow-x-auto" orientation="horizontal">

Render Props

Disabled

"use client";

import {Label, Switch} from "@heroui/react";

export function RenderProps() {

Form Integration

"use client";

import {Button, Label, Switch, SwitchGroup} from "@heroui/react";
import React from "react";

Custom Styles

"use client";

import {Check, Power} from "@gravity-ui/icons";
import {Switch} from "@heroui/react";

Related Components

Label

Description

Button

Styling

Passing Tailwind CSS classes

You can customize individual Switch components:

import { Switch, Label } from '@heroui/react';

function CustomSwitch() {
  return (
    <Switch>
      {({isSelected}) => (
        <>
          <Switch.Control
            className={`h-[31px] w-[51px] bg-blue-500 ${isSelected ? "bg-cyan-500 shadow-[0_0_12px_rgba(6,182,212,0.5)]" : ""}`}
          >
            <Switch.Thumb
              className={`size-[27px] bg-white shadow-sm ${isSelected ? "translate-x-5 shadow-lg" : ""}`}
            />
          </Switch.Control>
          <Label>Custom Switch</Label>
        </>
      )}
    </Switch>
  );
}

Or customize the SwitchGroup layout:

import { Switch, SwitchGroup, Label } from '@heroui/react';

function CustomSwitchGroup() {
  return (
    <SwitchGroup className="gap-8" orientation="horizontal">
      <Switch>
        <Switch.Control>
          <Switch.Thumb />
        </Switch.Control>
        <Label>Option 1</Label>
      </Switch>
      <Switch>
        <Switch.Control>
          <Switch.Thumb />
        </Switch.Control>
        <Label>Option 2</Label>
      </Switch>
    </SwitchGroup>
  );
}

Customizing the component classes

To customize the Switch component classes, you can use the @layer components directive.
Learn more.

@layer components {
  .switch {
    @apply inline-flex gap-3 items-center;
  }

  .switch__control {
    @apply h-5 w-8 bg-gray-400 data-[selected=true]:bg-blue-500;
  }

  .switch__thumb {
    @apply bg-white shadow-sm;
  }

  .switch__icon {
    @apply h-3 w-3 text-current;
  }
}

HeroUI follows the BEM methodology to ensure component variants and states are reusable and easy to customize.

CSS Classes

Switch Classes

The Switch component uses these CSS classes (View source styles):

.switch - Base switch container
.switch__control - Switch control track
.switch__thumb - Switch thumb that moves
.switch__icon - Optional icon inside the thumb
.switch--sm - Small size variant
.switch--md - Medium size variant (default)
.switch--lg - Large size variant

SwitchGroup Classes

The SwitchGroup component uses these CSS classes (View source styles):

.switch-group - Switch group container
.switch-group__items - Container for switch items
.switch-group--horizontal - Horizontal layout
.switch-group--vertical - Vertical layout (default)

Interactive States

The switch supports both CSS pseudo-classes and data attributes for flexibility:

Selected: [data-selected="true"] (thumb position and background color change)
Hover: :hover or [data-hovered="true"]
Focus: :focus-visible or [data-focus-visible="true"] (shows focus ring)
Disabled: :disabled or [aria-disabled="true"] (reduced opacity, no pointer events)
Pressed: :active or [data-pressed="true"]

API Reference

Switch Props

Inherits from React Aria Switch.

Prop	Type	Default	Description
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	The size of the switch
`isSelected`	`boolean`	`false`	Whether the switch is on
`defaultSelected`	`boolean`	`false`	Whether the switch is on by default (uncontrolled)
`isDisabled`	`boolean`	`false`	Whether the switch is disabled
`name`	`string`	-	The name of the input element, used when submitting an HTML form
`value`	`string`	-	The value of the input element, used when submitting an HTML form
`onChange`	`(isSelected: boolean) => void`	-	Handler called when the switch value changes
`onPress`	`(e: PressEvent) => void`	-	Handler called when the switch is pressed
`children`	`React.ReactNode \| (values: SwitchRenderProps) => React.ReactNode`	-	Switch content or render prop

SwitchRenderProps

When using the render prop pattern, these values are provided:

Prop	Type	Description
`isSelected`	`boolean`	Whether the switch is currently on
`isHovered`	`boolean`	Whether the switch is hovered
`isPressed`	`boolean`	Whether the switch is currently pressed
`isFocused`	`boolean`	Whether the switch is focused
`isFocusVisible`	`boolean`	Whether the switch is keyboard focused
`isDisabled`	`boolean`	Whether the switch is disabled
`isReadOnly`	`boolean`	Whether the switch is read only
`state`	`-`	State of the switch.

SwitchGroup Props

Prop	Type	Default	Description
`orientation`	`'horizontal' \| 'vertical'`	`'vertical'`	The orientation of the switch group
`children`	`React.ReactNode`	-	The switch items to render
`className`	`string`	-	Additional CSS class names

Related Components

On this page

Related Components