7onicDESIGN SYSTEM

ToggleGroup

ToggleGroup groups multiple Toggles together to manage on/off state. Supports both single and multiple selection modes.

2
Variants
5
Sizes
S/M
Mode
Radix
Base

Playground

Preview
outlineD
Type
Variant
Size
Radius
Direction
State
Label
Weight
<ToggleGroup type="single" variant="outline" defaultValue="grid">
  <ToggleGroup.Item value="grid" aria-label="Grid view">
    <LayoutGrid />
  </ToggleGroup.Item>
  <ToggleGroup.Item value="list" aria-label="List view">
    <List />
  </ToggleGroup.Item>
</ToggleGroup>

Types

Single
Only one item can be selected at a time. Use for mutually exclusive choices like text alignment.
Multiple
Multiple items can be selected simultaneously. Use for options that can be applied at the same time, like text formatting.

Variants

Default
No border — best for toolbars and compact UIs
Outline
Bordered and attached — use when grouping needs to be visually clear

Sizes

Icon Only

xs
Height28px
H. Padding10px
Icon14px
sm
Height32px
H. Padding12px
Icon14px
md
Height36px
H. Padding14px
Icon16px
default
Height40px
H. Padding16px
Icon16px
lg
Height48px
H. Padding24px
Icon16px

Icon + Text

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

Features

Use Cases

Grid / List view toggle

Finder, Dropbox, e-commerce product listings

Row / Column layout

Figma, Framer, Flexbox direction toggle

Card / Compact / Detail

Gmail, Notion, task management apps

// Grid/List toggle - Finder, Dropbox style
<ToggleGroup type="single" variant="outline" defaultValue="grid">
  <ToggleGroup.Item value="grid" aria-label="Grid view">
    <LayoutGrid />
  </ToggleGroup.Item>
  <ToggleGroup.Item value="list" aria-label="List view">
    <List />
  </ToggleGroup.Item>
</ToggleGroup>

// Row/Column layout - Figma, Framer style
<ToggleGroup type="single" variant="outline" defaultValue="rows">
  <ToggleGroup.Item value="rows" aria-label="Rows">
    <Rows />
  </ToggleGroup.Item>
  <ToggleGroup.Item value="columns" aria-label="Columns">
    <Columns />
  </ToggleGroup.Item>
</ToggleGroup>

// Card/Compact/Detail - Gmail, Notion style
<ToggleGroup type="single" variant="outline" defaultValue="card">
  <ToggleGroup.Item value="card" aria-label="Card view"><Grid /></ToggleGroup.Item>
  <ToggleGroup.Item value="compact" aria-label="Compact view"><List /></ToggleGroup.Item>
  <ToggleGroup.Item value="detail" aria-label="Detail view"><Rows /></ToggleGroup.Item>
</ToggleGroup>

States

Default

Normal state. Selected item is highlighted.

Disabled

All items are disabled.

Individual Disabled

Only specific items are disabled.

Multiple Selection

Multiple items can be selected simultaneously.

Orientation

Horizontal (Default)

Vertical

API

Component Structure

ToggleGroup— Radix ToggleGroup
.ItemProps

Props

ToggleGroup

type—
"single" | "multiple"

Single or multiple selection mode

valueundefined
string | string[]

Selected value in controlled mode

defaultValueundefined
string | string[]

Initial selected value in uncontrolled mode

onValueChangeundefined
(value) => void

Callback fired on selection change

variant"default"
"default" | "outline"

Visual style of items

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

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

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

Border radius size (6px)

fontWeight"normal"
"normal" | "semibold"

Font weight applied to all items. Can be overridden per item via fontWeight

orientation"horizontal"
"horizontal" | "vertical"

Layout direction

disabledfalse
boolean

Disables all items

ToggleGroup.Item

value—
string

Unique value for this item

disabledfalse
boolean

Disables this individual item

variantinherit
"default" | "outline"

Overrides variant for this item

sizeinherit
"xs" | "sm" | "md" | "default" | "lg"

Overrides size for this item

radiusinherit
"none" | "sm" | ... | "full"

Overrides radius for this item

fontWeightinherit
"normal" | "semibold"

Overrides font weight for this item

Customization

All items use default values based on the design system spacing rules. Use the group'sclassNameto customize all items at once.

Change horizontal padding

className="[&>button]:px-10"

Change Icon Only width

className="[&>button]:aspect-auto [&>button]:px-5"

Tip：Default values are designed to maintain component consistency. Use customization only when required for your UI implementation.

Anatomy

1
2
3
1
Root
Group container
2
Toggle Item
Individual toggle button
3
Active Item
Currently selected item

Best Practices

✓

Do

  • ✓Use type="single" for single selection
  • ✓Use type="multiple" for multiple selection
  • ✓Set aria-label on each item
  • ✓Group related options together
✕

Don't

  • ✗Don't include more than 5 items
  • ✗Don't mix unrelated options
  • ✗Don't use for navigation (→ use Tabs)
  • ✗Don't use instead of Segmented for single selection

Accessibility

Keyboard

TabMove focus to the group
SpaceToggle item on/off
EnterToggle item on/off
←→↑↓
Move between items

ARIA

  • role="group" Auto-applied
  • aria-pressed Auto-applied
  • data-orientation Auto-applied
  • aria-label Recommended

ToggleGroup vs ButtonGroup

They look similar but differ in purpose and behavior. Choose the appropriate component.

Purpose

ToggleGroup: Manage on/off state

ButtonGroup: Group action buttons

State management

ToggleGroup: Automatic (Radix-managed)

ButtonGroup: Manual (selected prop)

Selection mode

ToggleGroup: single / multiple

ButtonGroup: Manual control only

Value management

ToggleGroup: value / onValueChange

ButtonGroup: None

Use case

ToggleGroup: Text alignment, formatting

ButtonGroup: Pagination, toolbars

Use ToggleGroup when you need to retain state (selected/unselected), and ButtonGroup when you want to trigger an action on click.