Button Group Item
- 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";- 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.
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).
import { ButtonGroup, ButtonGroupItem } from "@nexera-ui/react";
import { LuColumns3, LuList, LuTable } from "react-icons/lu";
const sizes = ["sm", "md"] as const;
export function Sizes() {
return (
<div className="flex flex-col items-start gap-4">
{sizes.map((size) => (
<ButtonGroup key={size} aria-label={`View (${size})`} defaultSelectedKeys={["list"]}>
<ButtonGroupItem id="list" size={size} label="List" icon={<LuList />} />
<ButtonGroupItem id="board" size={size} label="Board" icon={<LuColumns3 />} />
<ButtonGroupItem id="table" size={size} label="Table" icon={<LuTable />} />
</ButtonGroup>
))}
</div>
);
}
Icon only
Figma Show label off: icon-only items are named by aria-label (pair them with a Tooltip).
import { ButtonGroup, ButtonGroupItem } from "@nexera-ui/react";
import { LuColumns3, LuList, LuTable } from "react-icons/lu";
export function IconOnly() {
return (
<ButtonGroup aria-label="View" defaultSelectedKeys={["board"]}>
<ButtonGroupItem id="list" aria-label="List" icon={<LuList />} />
<ButtonGroupItem id="board" aria-label="Board" icon={<LuColumns3 />} />
<ButtonGroupItem id="table" aria-label="Table" icon={<LuTable />} />
</ButtonGroup>
);
}
Multiple selection
selectionMode="multiple": a toolbar of toggle buttons (aria-pressed); several items can be selected.
import { ButtonGroup, ButtonGroupItem } from "@nexera-ui/react";
export function MultipleSelection() {
return (
<ButtonGroup
aria-label="Status filter"
selectionMode="multiple"
defaultSelectedKeys={["active", "remote"]}
>
<ButtonGroupItem id="active" label="Active" />
<ButtonGroupItem id="leave" label="On leave" />
<ButtonGroupItem id="remote" label="Remote" />
</ButtonGroup>
);
}
Disabled and only
Figma Disabled state on one item (isDisabled) and on a whole group, plus a lone item.
import { ButtonGroup, ButtonGroupItem } from "@nexera-ui/react";
export function DisabledAndOnly() {
return (
<div className="flex flex-col items-start gap-4">
<ButtonGroup aria-label="View" defaultSelectedKeys={["list"]}>
<ButtonGroupItem id="list" label="List" />
<ButtonGroupItem id="board" label="Board" isDisabled />
<ButtonGroupItem id="table" label="Table" />
</ButtonGroup>
<ButtonGroup aria-label="View (read only)" isDisabled defaultSelectedKeys={["board"]}>
<ButtonGroupItem id="list" label="List" />
<ButtonGroupItem id="board" label="Board" />
</ButtonGroup>
<ButtonGroup aria-label="Pinned">
<ButtonGroupItem id="only" label="Only" />
</ButtonGroup>
</div>
);
}
Long labels
Labels wrap instead of truncating (translation can add 30 to 40%); items share the row height.
import { ButtonGroup, ButtonGroupItem } from "@nexera-ui/react";
export function LongLabels() {
return (
<div className="max-w-xs">
<ButtonGroup aria-label="Period" defaultSelectedKeys={["month"]}>
<ButtonGroupItem id="month" label="This month" />
<ButtonGroupItem id="quarter" label="This quarter, including bank holidays" />
<ButtonGroupItem id="year" label="Year" />
</ButtonGroup>
</div>
);
}
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.
import { IconSlot, buttonGroupItemStyles } from "@nexera-ui/react";
import { LuList } from "react-icons/lu";
const sizes = ["sm", "md"] as const;
export function WithIconMatrix() {
return (
<div className="flex flex-col items-start gap-4 p-8">
{sizes.map((size) => (
<button
key={size}
type="button"
data-figma-variant={`Size=${size}, Position=Only, State=Default, Show icon=true`}
className={buttonGroupItemStyles({ size })}
>
<IconSlot className={buttonGroupItemIconStyles({ size })}>
<LuList />
</IconSlot>
<span>List</span>
</button>
))}
</div>
);
}
Props 19
Press "Try it" on a card to load that prop into the playground.
19 props shown
id*NexeraKeyKey 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.
iconNexeraReactNodeIcon before the label. Shown when provided;
decorative. An icon-only item needs aria-label or aria-labelledby.
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.
classNameNexerastringExtra classes, merged last so they win over the defaults.
styleNexeraCSSPropertiesInline style.
labelNexeraVisibleContentVisible label. It is the accessible name; it wraps and is never truncated. No visible label.
aria-labelNexerastringOverrides 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.
aria-labelledbyNexerastringId(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.
aria-describedbyReact AriastringIdentifies the element (or elements) that describes the object.
isSelectedReact AriabooleanWhether the element should be selected (controlled).
defaultSelectedReact AriabooleanWhether the element should be selected (uncontrolled).
onChangeReact Aria(isSelected: boolean) => voidHandler that is called when the element's selection state changes.
isDisabledReact AriabooleanWhether the button is disabled.
onPressReact Aria(e: PressEvent) => voidHandler that is called when the press is released over the target.
onPressStartReact Aria(e: PressEvent) => voidHandler that is called when a press interaction starts.
onPressEndReact Aria(e: PressEvent) => voidHandler that is called when a press interaction ends, either over the target or when the pointer leaves the target.
onPressChangeReact Aria(isPressed: boolean) => voidHandler that is called when the press state changes.
onPressUpReact Aria(e: PressEvent) => voidHandler that is called when a press is released over the target, regardless of whether it started on the target or not.
autoFocusReact AriabooleanWhether the element should receive focus on render.
* 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.
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-disableddata-focus-visibledata-hovereddata-selected
<ButtonGroupItem className="data-disabled:opacity-90 shadow-sm" />Used in blocks
No block uses ButtonGroupItem yet.
Related components
- BoardCardA Kanban card: avatar, name, role, drag handle and a detail line.
- ButtonTriggers an action such as Save, Submit, Approve or Delete.
- ContextMenuThe menu of actions for an element, opened where the user asks for it: right-click, long-press on touch screens, and from the keyboard with Shift+F10 or the ContextMenu key (the browser reports both as a `contextmenu` event on the focused element; on macOS, Control+Enter).
- DragHandleGrip that starts a drag of the collection item it sits in.
- DropIndicatorInsertion line shown between two items while something is dragged over a `GridList` or `ListBox`.
- IconButtonA square, icon-only button for compact actions such as Settings, Close or Delete row.
- MenuA list of actions or options that opens from a trigger.
- MenuDividerSeparates groups of items in a `Menu` or `ContextMenu`.