Theme studio

Design a theme, preview it live, then export it. Saved in this browser.

Quick picks #10b981
Generated scale
50100200300400500600700800900
Some text is below AA

ButtonGroupItem

  • Stable
  • WCAG 2.2 evidence
  • RTL

One toggle in a joined row of buttons, for example a List / Grid view switch or a set of filters. Place items directly inside a {@link ButtonGroup }: the group owns the selection (single: radios with aria-checked; multiple: toggle buttons with aria-pressed), arrow keys move focus between items and Tab leaves the group (WCAG 2.1.1, 4.1.2). The Figma Position (First, Middle, Last, Only) follows DOM order, so items must be direct children of the group. Built on React Aria ToggleButton; outside a group it is a standalone toggle with isSelected / defaultSelected / onChange. Consumer duties: the group's aria-label and the item wording; a Tooltip for icon-only items. The selected state is shown by fill, border and text colour only in Figma (no shape or weight change): see the WCAG 1.4.1 note in the docs.

import { ButtonGroupItem } from "@nexera-ui/react";
Loading example…
7
examples
19
props
3
live controls
1
platform
9
WCAG criteria
0
blocks use it

Try every prop. Copy the code.

Change the props and the code updates. Check light and dark, LTR and RTL, and phone width.

Loading…
size
isSelected
isDisabled
Generated code
import { ButtonGroupItem } from "@nexera-ui/react";

<ButtonGroupItem />

Examples 6

The same examples as Storybook, rendered live. Open Code to copy one.

Sizes

Both Figma sizes in a single-selection group (a radiogroup): 32 px (sm) and 40 px (md).

Loading example…

Icon only

Figma Show label off: icon-only items are named by aria-label (pair them with a Tooltip).

Loading example…

Multiple selection

selectionMode="multiple": a toolbar of toggle buttons (aria-pressed); several items can be selected.

Loading example…

Disabled and only

Figma Disabled state on one item (isDisabled) and on a whole group, plus a lone item.

Loading example…

Long labels

Labels wrap instead of truncating (translation can add 30 to 40%); items share the row height.

Loading example…

With icon matrix

Figma Show icon on: the icon box is 16 px at sm and 18 px at md, 8 px before the label.

Loading example…

Props 19

Press "Try it" on a card to load that prop into the playground.

19 props shown

id*Nexera
Key

Key of the item in the ButtonGroup selection (selectedKeys, onSelectionChange). Required: without it the group cannot track the item. On a standalone item it is used as the DOM id.

Default –
iconNexera
ReactNode

Icon before the label. Shown when provided; decorative. An icon-only item needs aria-label or aria-labelledby.

Default –
sizeNexera
"sm" | "md"

Height, padding and type: 32 px with Body/Strong, or 40 px with Component/Button. Heights follow the platform control tokens inside a mobile NexeraProvider scope.

Default "md"
classNameNexera
string

Extra classes, merged last so they win over the defaults.

Default –
styleNexera
CSSProperties

Inline style.

Default –
labelNexera
VisibleContent

Visible label. It is the accessible name; it wraps and is never truncated. No visible label.

Default –
aria-labelNexera
string

Overrides the name given by label. Avoid: the name must contain the visible text (WCAG 2.5.3). Accessible name of an icon-only item. Translate it, and show the same text in a Tooltip. Accessible name; aria-labelledby wins when both are set.

Default –
aria-labelledbyNexera
string

Id(s) of element(s) that name the item instead of label. Id(s) of element(s) that name the item; wins over aria-label. Id(s) of visible element(s) that name the item.

Default –
aria-describedbyReact Aria
string

Identifies the element (or elements) that describes the object.

Default –
isSelectedReact Aria
boolean

Whether the element should be selected (controlled).

Default –
defaultSelectedReact Aria
boolean

Whether the element should be selected (uncontrolled).

Default –
onChangeReact Aria
(isSelected: boolean) => void

Handler that is called when the element's selection state changes.

Default –
isDisabledReact Aria
boolean

Whether the button is disabled.

Default –
onPressReact Aria
(e: PressEvent) => void

Handler that is called when the press is released over the target.

Default –
onPressStartReact Aria
(e: PressEvent) => void

Handler that is called when a press interaction starts.

Default –
onPressEndReact Aria
(e: PressEvent) => void

Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target.

Default –
onPressChangeReact Aria
(isPressed: boolean) => void

Handler that is called when the press state changes.

Default –
onPressUpReact Aria
(e: PressEvent) => void

Handler that is called when a press is released over the target, regardless of whether it started on the target or not.

Default –
autoFocusReact Aria
boolean

Whether the element should receive focus on render.

Default –

* Required. React Aria props shown are the ones most apps use; the component accepts the rest of its React Aria props too.

Accessible by default.

Built on React Aria, and covered by the WCAG 2.2 evidence generated on every build.

WCAG 2.2 evidence

5 direct · 4 supporting
  • 1.1.1Non-text ContentLevel A · tested directly
  • 1.3.1Info and RelationshipsLevel A · tested directly
  • 1.4.4Resize TextLevel AA · supporting test
  • 1.4.11Non-text ContrastLevel AA · supporting test
  • 1.4.12Text SpacingLevel AA · supporting test
  • 2.1.1KeyboardLevel A · tested directly
  • 2.4.7Focus VisibleLevel AA · tested directly
  • 2.5.8Target Size (Minimum)Level AA · supporting test
  • 4.1.2Name, Role, ValueLevel A · tested directly

Fits any width.

Nexera components respond to the space they are given. Drag the corner of the frame, or pick a width.

0 px · drag the corner

Styling hooks

Pass className to add Tailwind classes (merged last). State is exposed as data attributes, so you can style it with variants like data-pressed:.

  • data-disabled
  • data-focus-visible
  • data-hovered
  • data-selected
Usage
<ButtonGroupItem className="data-disabled:opacity-90 shadow-sm" />

Used in blocks

No block uses ButtonGroupItem yet.

Related components