Design System/Atoms/Button Group

Button Group

Multiple related actions or view toggles presented as a unified control. Items share borders and appear as a single component.

Atom

Button

When To Use

  • Use buttons for explicit user-triggered actions such as submit, save, continue, or open.
  • Choose the variant and size that matches the action hierarchy in the surrounding view.
  • Prefer this page when you need to compare action density, icon usage, and loading or disabled states side by side.

When Not To Use

  • Do not use a button when plain text, static status, or passive decoration would communicate the state just as well.
  • Do not overload a single view with too many equally prominent buttons; reduce or demote secondary actions first.

Accessibility Notes

  • Keep headings, labels, and supporting text in the DOM before decorative chrome so the page reads well without styles or scripts.
  • Test the pattern with keyboard navigation and a screen reader before treating the visual layout as complete.
  • Use status, selection, and disabled states that remain understandable without color alone.

Key Props / API

Props

children, className, active

Key exports

ButtonGroup, ButtonGroupItem

Example Code

import { ButtonGroup, ButtonGroupItem } from "@hilum/ui"

<ButtonGroup>
  <ButtonGroupItem>Years</ButtonGroupItem>
  <ButtonGroupItem active>Months</ButtonGroupItem>
  <ButtonGroupItem>Days</ButtonGroupItem>
</ButtonGroup>

Button Group · Basic

Text items

Grouped text buttons with one active

Button Group · With Icons

Icon + label

Each item has an icon and text

Button Group · Variants

Icons only

Compact icon-only toggle (e.g. list vs grid)

With stat

Action button paired with a counter