Toggle Group

Segmented toggle controls for toolbars, filters, and formatting actions.

Installation

npx shadcn@latest add @iconiq/r-togglegroup

Props

ToggleGroup

Root container for a connected set of toggle buttons with shared variant, size, spacing, and orientation settings, layered over Radix UI toggle-group primitives.

type"single" | "multiple"

Default "multiple"

Selection mode. Multiple allows several active items by default; single keeps one pressed item at a time.

valuestring | string[]

Controlled selection. Pass a string for single mode or a string array for multiple mode.

defaultValuestring | string[]

Initial selection for uncontrolled usage in the matching single or multiple mode.

onValueChange(value: string | string[]) => void

Called with the next selection whenever an item is pressed or released.

variant"default" | "outline"

Default "default"

Shared visual treatment applied to every item unless an item overrides it locally.

size"default" | "sm" | "lg"

Default "default"

Shared height, padding, and icon sizing preset for all group items.

spacingnumber

Default 1

Gap between items in spacing units. Defaults to 1 (4px). Set to 0 to remove the gap.

orientation"horizontal" | "vertical"

Default "horizontal"

Layout direction for the group. Vertical stacks items and adjusts connected border handling.

disabledboolean

Disables the entire group and all nested items.

classNamestring

Merged onto the root group wrapper for local layout or width overrides.

Radix uses type="multiple" by default with a string array value. Pass type="single" for one active item.

Default spacing is 4px between items. Pass spacing={0} to remove the gap entirely.

Each item uses the same fluid wipe fill, sheen sweep, and icon press feedback as the standalone Toggle component.

Group items inherit variant and size from context but can override either prop locally.

ToggleGroupItem

Individual toggle button inside the group with the same fluid motion as the standalone toggle.

valuestring

Required

Stable identifier used when reading or updating the group selection.

variant"default" | "outline"

Optional local override for the shared group variant treatment.

size"default" | "sm" | "lg"

Optional local override for the shared group size preset.

disabledboolean

Disables this item without affecting the rest of the group.

classNamestring

Merged onto the item button for local width, color, or spacing overrides.

childrenReactNode

Icon or label content rendered inside the item. Pair icon-only items with aria-label.

Items render as Radix toggle-group buttons with the same fluid wipe fill, sheen sweep, and icon press feedback as the standalone toggle.

Items share the standalone toggle fluid motion system: liquid wipe fill, sheen sweep, and icon press squeeze.

Registry bundle

Install the exact registry entry shown on the right when you want the component file and its declared runtime dependencies together.

Dependencies: radix-ui, class-variance-authority, motion.

Installs a Radix toggle group with the same fluid motion as the standalone toggle.

Default spacing leaves a 4px gap between each bordered item.

Pass spacing={0} to pack items with no gap.

The generated registry file is /r/r-togglegroup.json.