Edit this page
[?] Component size, gzipped: 28kb

Button Group

Groups a collection of similar actions together.

When to use

  • If you need to emphasize context of similar actions.
  • If a single option or multiple options of the set may be selected.

Examples

Basic usage

With icons

With enhancers

Radio mode

In radio mode, the button group functions similarly to a radio group. Only one button can be "selected" at a time.

Checkbox mode

In checkbox mode, the button group functions similarly to a group of checkboxes. Multiple buttons can be "selected" at the same time.

Disabled button group

You can disable the entire button group as in the example above. Or you can disable isolated buttons as in the example below.

Single disabled button

With a dropdown

Stateful (uncontrolled) with radio mode

As with many of our components, there is also an uncontrolled version, StatefulButtonGroup, which manages its own state. If mode is set to radio or checkbox, this stateful version of the component will adapt to keep track of the selected value(s).

Stateful (uncontrolled) with checkbox mode

Overrides

Additionally, you can fully customize any part of the ButtonGroup through the overrides prop. The ButtonGroup consists of multiple subcomponents that are listed bellow and you can override each one of them. To help you identify the names of these subcomponents, you can highlight them through this selector:

Note: You should always use longhand CSS properties. Mixing shorthands and longhands will lead into strange behaviors!

API

ButtonGroup API

ariaLabel string

Accessible label.

children Array<Node> required

Set of more than one Button components

ArrayNode

disabled boolean = false

Defines if the button group is disabled.

mode $Values<typeof MODE>

Use the mode prop to render toggleable Buttons: the value radio will cause Buttons to behave like radio buttons, the value checkbox will cause Buttons to behave like checkboxes.

$ValuesObject.freeze({ radio: "radio", checkbox: "checkbox" })

onClick function = () => undefined

Called with click events from children. If a child button has its own click handler, the local handler will be called first, then this handler will trigger.

function
SyntheticEventHTMLButtonElement,
number
=> mixed

overrides { Root: { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }><<T>> }<*>

{ Root: { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }><<T>> }*

selected union

Index or array of indices of the selected Button(s). Primarily for use with controlled components with a mode prop defined.

One of
number,
Arraynumber

shape $Values<typeof SHAPE> =

Defines the shape of the buttons in the button group.

$Values{ default: "default", round: "round", square: "square" }

size $Values<typeof SIZE> =

Defines the size of the buttons in the button group.

$Values{ default: "default", compact: "compact", large: "large" }

StatefulButtonGroup API

StatefulContainer API

... $Diff<object, object> required

$Diff
ariaLabel string
children required ArrayNode
disabled boolean
mode $ValuesObject.freeze({ radio: "radio", checkbox: "checkbox" })
onClick function
SyntheticEventHTMLButtonElement,
number
=> mixed
overrides { Root: { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }><<T>> }*
selected union One of
number,
Arraynumber
shape $Values{ default: "default", round: "round", square: "square" }
size $Values{ default: "default", compact: "compact", large: "large" }
initialState object
selected union required One of
number,
Arraynumber
stateReducer function
$ValuesObject.freeze({ change: "change" }),
selected required Arraynumber
,
selected required Arraynumber
=>
selected required Arraynumber
,
selected mixed required

children function required

...$Diff<{ ariaLabel: string, children: Array<Node>, disabled: boolean, mode: $Values<typeof MODE>, onClick: (SyntheticEvent<HTMLButtonElement>, number) => mixed, overrides: { Root: { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }><<T>> }<*>, selected: number | Array<number>, shape: $Values<typeof SHAPE>, size: $Values<typeof SIZE> }, { children: mixed }>
onClick required function
SyntheticEventHTMLButtonElement,
number
=> mixed
selected union required One of
number,
Arraynumber
 => Node

ButtonGroup exports

You can import this module like so:

import {ButtonGroup} from 'baseui/button-group'

It exports the following components or utility functions:

  • ButtonGroup
  • StatefulButtonGroup
  • StatefulContainer
  • MODE
  • STATE_CHANGE_TYPE
  • StyledRoot