7onicDESIGN SYSTEM

Toggle

Toggle is a button that switches between on/off states. Use standalone or group with ToggleGroup.

4
Variants
5
Sizes
on/off
States
Radix
Base

Playground

Preview
defaultD
Variant
Size
Radius
Icon
Label
Weight
State
const [starred, setStarred] = useState(false)

<Toggle
  pressed={starred}
  onPressedChange={setStarred}
  iconOnly
  aria-label={starred ? "Unstar" : "Star"}
>
  <Star
    className={`transition-colors ${
      starred ? "fill-yellow-500 text-yellow-500" : ""
    }`}
  />
</Toggle>

Variants

Default
Background changes on press — ideal for toolbars and compact UI
Outline
Bordered style — state is clearly visible
Ghost
No background change — state shown through icon color only, ideal for like buttons
Outline Ghost
Border + icon-only state — clear boundary with minimal visual change

Sizes

Icon Only (iconOnly=true)

xs
Size28px × 28px
Icon14px
sm
Size32px × 32px
Icon16px
md
Size36px × 36px
Icon16px
default
Size40px × 40px
Icon20px
lg
Size48px × 48px
Icon24px

Icon + Text (iconOnly=false)

xs
Height28px
H Padding10px
Gap4px
Icon14px
Font12px
sm
Height32px
H Padding12px
Gap8px
Icon14px
Font13px
md
Height36px
H Padding14px
Gap8px
Icon16px
Font14px
default
Height40px
H Padding16px
Gap8px
Icon16px
Font14px
lg
Height48px
H Padding24px
Gap8px
Icon16px
Font16px

States

Off
On
Disabled
Disabled On
<Toggle iconOnly variant="outline" aria-label="Off"><Star className="icon-xl" /></Toggle>
<Toggle iconOnly variant="outline" defaultPressed aria-label="On"><Star className="icon-xl fill-yellow-500 text-yellow-500" /></Toggle>
<Toggle iconOnly variant="outline" disabled aria-label="Disabled"><Star className="icon-xl" /></Toggle>
<Toggle iconOnly variant="outline" disabled defaultPressed aria-label="Disabled on"><Star className="icon-xl fill-yellow-500 text-yellow-500" /></Toggle>

API

Props

pressedundefined
boolean

On/off state for controlled mode

defaultPressedfalse
boolean

Initial state for uncontrolled mode

onPressedChangeundefined
(pressed: boolean) => void

Callback on state change

variant"default"
"default" | "outline" | "ghost" | "outline-ghost"

Visual style. ghost/outline-ghost have no background change (icon color only)

size"default"
"xs" | "sm" | "md" | "default" | "lg"

Toggle size (28/32/36/40/48px)

radius"default"
"none" | "sm" | "base" | "default" | "lg" | "xl" | "2xl" | "3xl" | "full"

Border radius (6px)

fontWeight"normal"
"normal" | "semibold"

Font weight. normal=400, semibold=600

iconOnlyundefined
boolean

Icon-only mode. Square layout with IconButton sizing rules

pressEffectundefined
boolean

Press effect (active:scale-pressed). Defaults to true. Set false to disable

disabledfalse
boolean

Disabled state

asChildfalse
boolean

Render as Slot

Anatomy

1
2
3
Favorite
statedata-[state=on/off]
1
Container
Toggle button body
2
Icon
Optional
3
Label
Optional

Best Practices

✓

Recommended

  • ✓Visually indicate clear on/off states
  • ✓Describe purpose with aria-label
  • ✓Use for immediate-effect actions
  • ✓Group multiple toggles with ToggleGroup
✕

Avoid

  • ✗Don't use for form items that need submission
  • ✗Don't use icons with unclear state indication
  • ✗Don't use without aria-label
  • ✗Use Segmented for exclusive selection

Accessibility

Keyboard

SpaceToggle
EnterToggle

ARIA Attributes

  • aria-pressed Auto-applied
  • data-state on/off
  • Focus indicator
  • aria-label Recommended