Clinia UI

Toggle

A two-state button that can be on or off.

shadcn docs →

When to use

  • A button that stays pressed to show a state: a filter panel, a favourite, bold text.

When not to use

  • A one-time action, such as delete or export: use Button.
  • A setting that persists, such as notifications: use Switch.
  • Several related toggles, such as a view switcher: use Toggle Group.

Install

npx shadcn@latest add @clinia/toggle

Clinia rules

  • Pressed is a Trust border (border-emphasis) over a bg-accent/15 tint with text-foreground. The label never turns Trust.
  • default has no border at rest, for toolbars. outline has an input border, for a toggle that stands alone.
  • The label stays the same when pressed. The pressed style shows the state, so don't swap Show filters for Hide filters.

Do and don't

Do use it for a state that stays on, such as a filter panel.
Don't use it for a one-time action: use Button.

States

off
pressed
outline
outline · pressed
hover
focus
disabled

Focus cells apply the component's focus-visible classes statically. Toggle the site theme to review both themes.

Sizes

SizeHeightPadding xGapRadiusType
defaulth-9 · 36pxpx-3 · 12pxgap-1 · 4px--radius-lgtext-sm · 14px
smh-8 · 32pxpx-3 · 12pxgap-1 · 4px--radius-lgtext-sm · 14px
lgh-10 · 40pxpx-4 · 16pxgap-1 · 4px--radius-lgtext-sm · 14px

Accessibility

Built in

  • Pressed shows a Trust border (border-emphasis, 3:1 or more in both themes) over a bg-accent/15 tint. Upstream uses bg-muted, which is 1.06:1 on the white background and does not show the state.
  • Base UI renders a native button with aria-pressed.

Your responsibility

  • Give an icon-only toggle an aria-label that names what it turns on, such as Favorite, not the action.
  • Don't change the aria-label when pressed: aria-pressed already tells a screen reader the state.

How to test

  1. Press Tab to reach the toggle: the Trust ring appears.
  2. Press Enter or Space: it switches between pressed and not pressed, and the Trust border appears or goes.
  3. With a screen reader, it's announced as its label, then toggle button, then pressed or not pressed.

API

PropValuesDefaultDescription
variant
defaultoutline
default

outline adds a border, for a toggle that stands alone.

size
defaultsmlg
default

Height: sm 32px, default 36px, lg 40px.

All other props come from Base UI Toggle.

Related