Variants

Use the variant prop to determine if the buttons are icon-only or text. For variant="text", optional icon on each <ToggleButton /> renders a leading icon (pill tab pattern). Text buttons will have uniform size based on the largest button.

For pill segmented controls (Global Library “Pill Tab”), use variant="text", buttonShape="pill", and colorVariant="primary".

Color Variants

Available color variants: neutral (default), accent and primary.

Outlined

Use the hasOutline prop to add a visible outline around the group.

Button Shape

Use optional "Pill" Button-Shape

Sizes

Available sizes: small, medium (default), and large

Props

ToggleButtonGroup
System Props

  • COMMON
  • TYPOGRAPHY
  • BORDER
  • LAYOUT
  • POSITION
  • FLEX
  • GRID
  • Learn More
NameTypeDescription
gradientResponsiveValue<BackgroundProperty<TLengthStyledSystem>, Required<Theme<TLengthStyledSystem>>>-
aria-label*stringBecause toggle buttons aren't meant to have a visible label, this is required
valuestringUse for controlled
defaultValuestringUse for uncontrolled
onChange(evt: MouseEvent<HTMLButtonElement, MouseEvent>, newValue: string) => voidEvent handler for when the value changes, receives both the click event and the new value
variant"text" | "icon"The type of content in each button
icon
colorVariant"neutral" | "accent" | "primary"Defines the color variant of each button in the group
neutral
buttonShape"default" | "pill"Optional "pill" shape for the grouped buttons
default
hasOutlinebooleanWhether the group has an outline
false
size"small" | "medium" | "large"Defines the size variant of each button in the group
medium
ToggleButton
System Props

NameTypeDescription
buttonShape"default" | "pill"-
iconReactNodeIcon name or component.
aria-labelstringFor pure icon buttons, pass in a label to describe the purpose of the button.

Accessibility

  • <ToggleButtonGroup /> needs aria-label since these aren't designed to have a visible label
  • For <ToggleButton variant="icon" />, aria-label should be provided
  • Each <ToggleButton /> sets aria-pressed to reflect whether it is the selected option in the group (mutually exclusive selection)
  • When switching views with associated panels (e.g. settings sections), prefer <Tabs /> with correct tablist / tabpanel semantics instead of toggle buttons