Button Group

A Button Group is a set of related buttons displayed together in a horizontal or vertical arrangement, visually connected to indicate shared context.

Use Button Groups to group similar actions, present mutually exclusive choices, or align secondary actions with a primary action, ideal for toolbars, segmented controls, or grouped form actions.

Common alternative names:
Segmented Control, Action Group, Toolbar Buttons

---

Variants

Basic

A simple button group with text-only options.

Preview

Code

ButtonGroup(
  onOptionSelected: (index) {
    debugPrint('Selected index: $index');
  },
  options: const [
    ButtonGroupOption(label: 'Option 1'),
    ButtonGroupOption(label: 'Option 2'),
    ButtonGroupOption(label: 'Option 3'),
  ],
)

---

With Icons

A button group with icons alongside text labels.

Preview

Code

ButtonGroup(
  onOptionSelected: (index) {
    debugPrint('Selected index: $index');
  },
  options: [
    ButtonGroupOption(
      label: 'Option 1',
      icon: SvgPicture.asset('assets/cube.svg', width: 16),
    ),
    ButtonGroupOption(
      label: 'Option 2',
      icon: SvgPicture.asset('assets/cube.svg', width: 16),
    ),
    ButtonGroupOption(
      label: 'Option 3',
      icon: SvgPicture.asset('assets/cube.svg', width: 16),
    ),
  ],
)

---

Properties

Property	Type	Description
options	List<ButtonGroupOption>	The list of options to display in the button group.
onOptionSelected	Function(int)	Callback function when an option is selected. Receives the index of the selected option.
textStyle	TextStyle?	Custom text style for the button labels. Defaults to semiBold14 with accent color.
radius	double	The border radius of the button group’s outer corners. Defaults to 100.
backgroundColor	Color?	Background color of the buttons. If not provided, uses default background.

ButtonGroupOption Properties

Property	Type	Description
label	String	The text to be displayed for this option.
icon	Widget?	An optional icon widget to display before the label.