Components

Toggle Group

A set of related toggles that behave as a single control.

Basic example

Installation

Choose the package when you want centralized updates, or copy the source through the registry when you want local ownership.

@constructive-io/ui

Install the package, import its global tokens once, then use this exact subpath.

# install

pnpm add @constructive-io/ui

# app/globals.css

@import '@constructive-io/ui/globals.css';

# import

import { ToggleGroup } from '@constructive-io/ui/toggle-group';

When to use

Use Toggle Group for a small set of related options rendered as attached controls, such as text alignment, density, or a time-range picker.
Use Tabs when each option swaps a whole panel of content. Use Radio Group inside forms, and Button Group when the controls trigger actions rather than hold selection.

Basic usage

Group ToggleGroupItem children inside ToggleGroup. spacing={0} renders the attached segmented style; larger spacing gaps items so each keeps its own radius.

npm source

tsx

'use client';
import { ToggleGroup, ToggleGroupItem } from '@constructive-io/ui/toggle-group';
export function BasicToggleGroupDemo() {
    return (<ToggleGroup defaultValue={['24h']} aria-label="Metrics window">
        <ToggleGroupItem value="1h">1h</ToggleGroupItem>
        <ToggleGroupItem value="24h">24h</ToggleGroupItem>
        <ToggleGroupItem value="7d">7d</ToggleGroupItem>
        <ToggleGroupItem value="30d">30d</ToggleGroupItem>
      </ToggleGroup>);
}

Single and multiple selection

By default one item is selected at a time and a highlight pill slides under the pressed item. Set multiple to allow several pressed items, each painting its own accent fill. Use defaultValue for uncontrolled state or value and onValueChange for controlled state.

Single and multiple selection

Showing errors.

Examples

01Gapped groupSet spacing above 0 to separate the items while keeping the shared group semantics.

Accessibility

Give every icon-only ToggleGroupItem an aria-label. The group moves focus with arrow keys, so each item needs its own name.
Choose multiple deliberately — single-select communicates one-of, while multi-select communicates any-of, and the difference matters to assistive technology.
Keep the group next to the content it controls so the relationship is clear without a visible label.

API Reference

Constructive-specific behavior is listed here. Each part links to its inherited platform or primitive contract.

ToggleGroup

Base UI toggle group with a sliding highlight in single-select mode.

Prop	Type	Default	Description
value	string[]	—	Controlled selected item values.
defaultValue	string[]	—	Initial uncontrolled selection.
onValueChange	(value: string[], eventDetails) => void	—	Runs when the selection changes.
multiple	boolean	false	Allows more than one pressed item.
spacing	number	0	Pixel gap between items; 0 renders the attached segmented style.
orientation	'horizontal' \| 'vertical'	'horizontal'	Direction items are laid out.
variant	'default' \| 'outline'	'default'	Visual treatment applied to items.
size	'sm' \| 'default' \| 'lg'	'default'	Size applied to items.

Also accepts Base UI Toggle Group props.

ToggleGroupItem

One selectable item inside the group.

Prop	Type	Default	Description
value *	string	—	Value reported by the group when this item is selected.
disabled	boolean	false	Prevents selecting this item.

Also accepts Base UI Toggle Group props.