Toggle Group

Guidelines
React API Reference

Toggle groups are interactive components that allow users to select one or more options from a set of related choices. They combine the functionality of toggle buttons into a cohesive group, supporting both single and multiple selection modes. Toggle groups are ideal for formatting controls, view modes, or any scenario where users need to make selections from mutually exclusive or inclusive options.

Guidance

Aspect	Best Practice
Usage	Use toggle groups for related options where users can select one or multiple items, such as text formatting or view options.
Content	Use clear, concise labels or icons that immediately communicate the function of each toggle option.
Behavior	Support both single selection (radio-like) and multiple selection (checkbox-like) modes based on user needs.
States	Provide clear visual feedback for active, inactive, hover, focus, and disabled states.
Grouping	Group related toggle options together and separate different groups with appropriate spacing.
Examples	Text formatting controls (bold, italic, underline), alignment options, view modes, or filter selections.

Best Practices

Clear Visual States: Ensure active and inactive states are clearly distinguishable through color, iconography, or typography changes.
Consistent Sizing: Maintain consistent button sizes within a group for visual harmony and predictable interaction areas.
Logical Grouping: Group related functionality together and use appropriate spacing between different toggle groups.
Accessible Labels: Provide descriptive labels or aria-labels for screen readers, especially when using icon-only toggles.
Keyboard Navigation: Support full keyboard navigation with arrow keys and space/enter for activation.

Do’s and Don’ts

Do

Use toggle groups for related options that can be selected together.
Provide clear visual feedback for active states.
Support both single and multiple selection modes appropriately. * Use consistent sizing and spacing within groups.

Don't

Mix unrelated functionality in the same toggle group.
Make active states too subtle or unclear.
Use toggle groups for actions that should be immediate buttons.
Overcrowd groups with too many options.

Additional Guidance

Accessibility: Toggle groups must support keyboard navigation, screen reader announcements, and proper ARIA attributes for selection states.
Psychological Impact:
- Decision Making: Toggle groups help users make clear choices by presenting options in a structured, comparable format.
- Visual Grouping: The grouped presentation helps users understand that options are related and can be compared.
- Feedback Clarity: Clear active/inactive states provide immediate feedback, building user confidence in their selections.

Import

import {
  ToggleGroup,
  ToggleGroupItem
} from '@strongtie/design-system/toggle-group';

Usage

<ToggleGroup type='single'>
  <ToggleGroupItem value='1'>Toggle 1</ToggleGroupItem>
  <ToggleGroupItem value='2'>Toggle 2</ToggleGroupItem>
  <ToggleGroupItem value='3'>Toggle 3</ToggleGroupItem>
</ToggleGroup>

`<ToggleGroup>` Props

asChild

boolean

default:"false"

Change the default rendered element for the one passed as a child, merging their props and behavior.

type

"single" | "multiple"

required

Determines the selection behavior. “single” allows only one selection at a time, “multiple” allows multiple selections.

value

string | string[]

default:"undefined"

The controlled value(s) of the toggle group. For single type, use string. For multiple type, use string array.

defaultValue

string | string[]

default:"undefined"

The default value(s) when the component is uncontrolled.

onValueChange

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

default:"undefined"

Callback fired when the value changes.

disabled

boolean

default:"false"

Whether the entire toggle group is disabled.

rovingFocus

boolean

default:"true"

Whether to use roving tabindex for keyboard navigation.

orientation

"horizontal" | "vertical"

default:"undefined"

The orientation of the toggle group.

dir

"ltr" | "rtl"

default:"undefined"

The reading direction of the toggle group. If omitted, inherits globally or assumes LTR.

loop

boolean

default:"true"

Whether keyboard navigation should loop from last to first item.

variant

"default" | "outline"

default:"\"default\""

The visual variant of the toggle buttons.

size

"sm" | "default" | "lg"

default:"\"default\""

The size of the toggle buttons.

`<ToggleGroupItem>` Props

asChild

boolean

default:"false"

Change the default rendered element for the one passed as a child, merging their props and behavior.

value

string

required

The unique value for this toggle item.

disabled

boolean

default:"false"

Whether this specific toggle item is disabled.

variant

"default" | "outline"

default:"inherited"

Override the variant for this specific item. Falls back to group variant.

size

"sm" | "default" | "lg"

default:"inherited"

Override the size for this specific item. Falls back to group size.

Styling Classes

The component applies the following CSS classes:

toggle-group - Base toggle group container class
Toggle items inherit classes from the toggle component based on variant and size

Usage Examples

<ToggleGroup type="single" defaultValue="center">
  <ToggleGroupItem value="left">Left</ToggleGroupItem>
  <ToggleGroupItem value="center">Center</ToggleGroupItem>
  <ToggleGroupItem value="right">Right</ToggleGroupItem>
</ToggleGroup>

For more examples, visit the Storybook.

Getting Started

Foundations

Components

Integration Guides

Content

Toggle Group

Guidance

Best Practices

Do’s and Don’ts

Do

Don't

Additional Guidance

`<ToggleGroup>` Props

`<ToggleGroupItem>` Props

Styling Classes

Usage Examples

Getting Started

Foundations

Components

Integration Guides

Content

​Guidance

​Best Practices

​Do’s and Don’ts

Do

Don't

​Additional Guidance

​<ToggleGroup> Props

​<ToggleGroupItem> Props

​Styling Classes

​Usage Examples

Guidance

Best Practices

Do’s and Don’ts

Additional Guidance

`<ToggleGroup>` Props

`<ToggleGroupItem>` Props

Styling Classes

Usage Examples