Button group

01Preview

Change the controls to try every supported combination. The preview renders the real component, every item works, and the code updates with it.

import { ButtonGroup, ButtonGroupItem } from '@nuton/ui'

const [selected, setSelected] = useState('List')

<ButtonGroup aria-label="Lesson view">
  <ButtonGroupItem pressed={selected === 'List'} onClick={() => setSelected('List')}>List</ButtonGroupItem>
  <ButtonGroupItem pressed={selected === 'Grid'} onClick={() => setSelected('Grid')}>Grid</ButtonGroupItem>
  <ButtonGroupItem pressed={selected === 'Board'} onClick={() => setSelected('Board')}>Board</ButtonGroupItem>
</ButtonGroup>

02Installation

1. Add the packages

pnpm add @nuton/ui @nuton/tokens @remixicon/react

npm install @nuton/ui @nuton/tokens @remixicon/react

yarn add @nuton/ui @nuton/tokens @remixicon/react

Peer dependencies: react and react-dom 18 or later. @remixicon/react supplies the icons you pass to items (Remix Icon is Nuton's icon set, D1).

2. Load tokens and component styles once

// app/layout.tsx (or your app's entry file)
import '@nuton/tokens/tokens.css' // --nu-* design tokens
import '@nuton/ui/styles.css'     // component styles (uses the tokens)

Item labels use --nu-font-body (Inter), the same font token as Button. If you haven't mapped it yet, follow the font setup on the Button page. No provider is needed: ButtonGroup passes its size to its items itself.

03Usage

import { useState } from 'react'
import { ButtonGroup, ButtonGroupItem } from '@nuton/ui'

export function ProgressRange() {
  const [range, setRange] = useState('Week')
  return (
    <ButtonGroup aria-label="Progress range" size="xs">
      {['Day', 'Week', 'Month'].map((r) => (
        <ButtonGroupItem key={r} pressed={range === r} onClick={() => setRange(r)}>{r}</ButtonGroupItem>
      ))}
    </ButtonGroup>
  )
}

• The default is sm, smooth: a 36px pill. Every ButtonGroupItem must sit directly inside a ButtonGroup.
• Always name the group with aria-label or aria-labelledby. It renders role="group" and warns in development without a name.
• For options (one is chosen), pass pressed to every item and update it on click. For plain actions, leave pressed undefined.
• Keep to 2–6 items with short, parallel labels in sentence case: “Day”, “Week”, “Month”.
• type defaults to "button", so items never submit a surrounding form by accident.

04Variants and sizes

A button group is one of two patterns, set by how you use pressed. Size and corners apply to the whole group; items take their size from it.

Single select or actions

Sizes

const ranges = ['Day', 'Week', 'Month']
const [range, setRange] = useState('Week')

{(['sm', 'xs', '2xs'] as const).map((size) => (
  <ButtonGroup key={size} size={size} aria-label={`Progress range, ${size}`}>
    {ranges.map((r) => (
      <ButtonGroupItem key={r} pressed={range === r} onClick={() => setRange(r)}>{r}</ButtonGroupItem>
    ))}
  </ButtonGroup>
))}

Heights are the outer group, including its 1px border; items sit inside that border and are separated by 1px Stroke/Soft-200 dividers, so an icon-only item is 2px smaller than the group height. The code uses Figma's labelled sizes (36/32/24), which match its icon variants. Figma's text-only items measure 32/28/24 under the same labels; that discrepancy is open (C11, FC-09).

Corners

const ranges = ['Day', 'Week', 'Month']
const [range, setRange] = useState('Week')

{(['smooth', 'rounded', 'sharp'] as const).map((corners) => (
  <ButtonGroup key={corners} size="xs" corners={corners} aria-label={`Progress range, ${corners}`}>
    {ranges.map((r) => (
      <ButtonGroupItem key={r} pressed={range === r} onClick={() => setRange(r)}>{r}</ButtonGroupItem>
    ))}
  </ButtonGroup>
))}

Radius tokens: smooth --nu-radius-full, rounded --nu-radius-8 (--nu-radius-6 at 2xs), sharp --nu-radius-0. Figma calls this property Type. Match the corner style of the buttons around the group.

Quantity

Figma defines groups of 2 to 6 items (Quantity 02–06). The component doesn't enforce a count; it renders the items you pass.

const terms = ['Day', 'Week', 'Month', 'Term', 'Year', 'All']

{[2, 3, 4, 5, 6].map((count) => (
  <ButtonGroup key={count} size="xs" aria-label={`Progress range, ${count} options`}>
    {terms.slice(0, count).map((t) => (
      <ButtonGroupItem key={t} pressed={selected[count] === t} onClick={() => select(count, t)}>{t}</ButtonGroupItem>
    ))}
  </ButtonGroup>
))}

Icons

<ButtonGroup size="sm" aria-label="Lesson view">
  <ButtonGroupItem leadingIcon={<RiListUnordered />} pressed={view === 'list'} onClick={() => setView('list')}>List</ButtonGroupItem>
  <ButtonGroupItem leadingIcon={<RiLayoutGridLine />} pressed={view === 'grid'} onClick={() => setView('grid')}>Grid</ButtonGroupItem>
</ButtonGroup>

<ButtonGroup size="sm" aria-label="Text formatting">
  <ButtonGroupItem iconOnly aria-label="Bold" pressed={marks.bold} onClick={() => toggle('bold')}><RiBold /></ButtonGroupItem>
  <ButtonGroupItem iconOnly aria-label="Italic" pressed={marks.italic} onClick={() => toggle('italic')}><RiItalic /></ButtonGroupItem>
  <ButtonGroupItem iconOnly aria-label="Underline" pressed={marks.underline} onClick={() => toggle('underline')}><RiUnderline /></ButtonGroupItem>
</ButtonGroup>

leadingIcon and trailingIcon sit beside the label (see the flashcard example below for a trailing icon). With iconOnly, children is the icon and the item becomes square; both icon props are then ignored. Icons are rendered aria-hidden.

05States and interactions

States belong to items. Every group below works: click an item to change the selection.

State tokens

Button group has no component-level colour tokens: items read the semantic tokens below directly. Change them only through the theme, never per group.

06Composition examples

Progress range

A single-select group that changes the period a progress summary covers. The result is announced through a status region.

const [range, setRange] = useState('Week')

<ButtonGroup size="xs" aria-label="Progress range">
  {['Day', 'Week', 'Month'].map((r) => (
    <ButtonGroupItem key={r} pressed={range === r} onClick={() => setRange(r)}>{r}</ButtonGroupItem>
  ))}
</ButtonGroup>
<p role="status">Study time in Biology 101: {studyTime[range]}</p>

Note formatting

Independent toggles: each icon-only item turns its own style on or off, so any combination can be pressed.

<ButtonGroup size="xs" corners="rounded" aria-label="Text formatting">
  <ButtonGroupItem iconOnly aria-label="Bold" pressed={marks.bold} onClick={() => toggle('bold')}><RiBold /></ButtonGroupItem>
  <ButtonGroupItem iconOnly aria-label="Italic" pressed={marks.italic} onClick={() => toggle('italic')}><RiItalic /></ButtonGroupItem>
  <ButtonGroupItem iconOnly aria-label="Underline" pressed={marks.underline} onClick={() => toggle('underline')}><RiUnderline /></ButtonGroupItem>
</ButtonGroup>

Flashcard actions

A plain action group: no pressed, so the items are ordinary buttons. Previous and next move through the deck in place, so they're actions, not links.

<ButtonGroup size="sm" aria-label="Flashcards">
  <ButtonGroupItem leadingIcon={<RiArrowLeftSLine />} onClick={previous}>Previous card</ButtonGroupItem>
  <ButtonGroupItem trailingIcon={<RiArrowRightSLine />} onClick={next}>Next card</ButtonGroupItem>
</ButtonGroup>
<p role="status">Card {card} of {total}</p>

Semantics and navigation

• Button group is a set of buttons in a role="group", not tabs or a radio group. Each item is its own tab stop and arrow keys don't move between items.
• If choosing an option swaps a whole panel of content, the tabs pattern fits better. If the choice is part of a form that gets submitted, use a select or radio inputs.
• Items always render <button>. If an option goes to another page, use links, for example Link button.
• The group doesn't wrap. On narrow screens, keep labels short, use fewer items, or move to a Dropdown menu.

07API reference

ButtonGroup props

ButtonGroupItem props

Styling hooks

The group renders .nu-button-group with data-size and data-corners; items render .nu-button-group__item with data-icon-only and aria-pressed, and icons sit in .nu-button-group__icon. The size sets internal spacing variables (--nu-bg-item-pad-block, --nu-bg-item-pad-inline, --nu-bg-item-gap). Use props rather than styling these; they aren't a supported override point.

Accessibility

You must: name every group with aria-label or aria-labelledby; give icon-only items an aria-label; set pressed on every item of a single-select group and keep exactly one true; avoid 2xs for icon-only items until C26 is resolved.

Figma mapping

08Guidelines and related components

Do and don't

Common mistakes

• Forgetting the group's aria-label, so screen readers announce an unnamed group.
• Setting pressed only on the selected item. The others render no aria-pressed and read as plain buttons; pass false to them.
• Using pressed on action items (Undo, Share). Actions aren't on or off; leave it undefined.
• Rendering ButtonGroupItem outside a ButtonGroup: it gets no size or border styling and warns in development.
• Navigating from onClick instead of using links.

Related components

• ButtonA single action, or actions of different importance.
• Link buttonNavigation and low-emphasis actions that look like links.
• Dropdown menuMore than 6 options, or overflow actions.
• Chart legendPairs with a range group above progress charts.