Switch

Usage

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

<ComponentPreview name="switch-basic" />

Anatomy

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

export default () => (
  <Switch>
    <Switch.Control>
      <Switch.Thumb>
        <Switch.Icon/>
      </Switch.Thumb>
    </Switch.Control>
    <Switch.Content>
      <Label />
      <Description />
    </Switch.Content>
  </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>
);

Examples

Sizes

<ComponentPreview name="switch-sizes" />

With Icons

<ComponentPreview name="switch-with-icons" />

Disabled

<ComponentPreview name="switch-disabled" />

Without Label

<ComponentPreview name="switch-without-label" />

With Description

<ComponentPreview name="switch-with-description" />

Default Selected

<ComponentPreview name="switch-default-selected" />

Controlled

<ComponentPreview name="switch-controlled" />

Label Position

<ComponentPreview name="switch-label-position" />

Group

<ComponentPreview name="switch-group" />

Group Horizontal

<ComponentPreview name="switch-group-horizontal" />

Form Integration

<ComponentPreview name="switch-form" />

Render Props

<ComponentPreview name="switch-render-props" />

Render Function

<ComponentPreview name="switch-render-function" />

Customization

Tailwind CSS

Global CSS

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__content {
    @apply flex flex-col gap-1;
  }

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

Styling Reference

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

CSS Classes

Switch Classes [!toc]

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

• .switch - Base switch container
• .switch__content - Optional content 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 [!toc]

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

Inherits from React Aria Switch.

Render Props

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

SwitchGroup

Related Components