Button group

EuiButtonGroup groups related buttons together. There are two APIs available:

Children API — pass EuiButton, EuiButtonEmpty, or EuiButtonIcon directly as children for an arrangement of mixed button types in a row.
Options API — pass an options array when buttons need radio or checkbox semantics (type="single" or "multi").

Accessibility recommendation

The legend prop is required on both APIs. In the children API it is rendered as an aria-label on the group wrapper (role="group"). In the options API it is visibly hidden inside a <fieldset>.

Children API

This usage arranges buttons in a row and passes certain props (buttonSize, isDisabled, and hasAriaDisabled) to all children to ensure a cohesive output.

Pass any combination of EuiButton, EuiButtonEmpty, and EuiButtonIcon directly as children. This also supports a selection of composable wrappers around those button components: EuiToolTip, EuiPopover and EuiCopy.

Gutter size

The gutterSize prop is only available for the children API when used with variant="default".

Control the gap between children with the gutterSize prop. The default is "s". Use "none" to remove the gap entirely.

Options API

Use the options array when buttons need radio or checkbox semantics. Set type="single" (default) for a radio-like single selection, or type="multi" for multi-selection.

Accessibility recommendation

In order for groups to be properly read as groups with a title, the legend prop is required. This is only for accessibility, however, so it will be visibly hidden.

Icon only button group

Use the isIconOnly prop when displaying a group of icon-only buttons.

Button group tooltips

Buttons within a button group will automatically display a default browser tooltip containing the button label text. This can be customized or unset via the title property in your options button configuration.

To instead display an EuiToolTip around your button(s), pass the toolTipContent property. You can also use toolTipProps to customize tooltip placement, title, and any other prop that EuiToolTip accepts.

Beta feature: Showing tooltips on disabled EuiButtonGroup

If you need disabled buttons to show tooltips, add the hasAriaDisabled prop to switch from native to custom disabled behavior which preserves focusability. Read more about custom disabled behavior.

Button group in forms

Pattern

When using button groups within compressed forms, match the form elements by adding buttonSize="compressed". Compressed groups should always be fullWidth so they line up nicely in their small container unless they are icon only.

For a more detailed example of how to integrate with forms, see the "Complex example" on the compressed forms page.

Props

EuiButtonGroupChildrenProps


Prop	Description and type	Default value
Prop legend#	Description and type A group title (required for accessibility). Rendered as `aria-label` on the group element. Type: `string`	Default value Required
Prop children#	Description and type Pass button components (`EuiButton`, `EuiButtonEmpty`, `EuiButtonIcon`) as children, some specific wrappers, like `EuiToolTip` and `EuiPopover` are allowed. Type: `ReactNode`	Default value Required
Prop className#	Description and type Type: `string`	Default value
Prop aria-label#	Description and type Type: `string`	Default value
Prop data-test-subj#	Description and type Type: `string`	Default value
Prop css#	Description and type Type: `Interpolation<Theme>`	Default value
Prop isDisabled#	Description and type Controls the disabled behavior via the native `disabled` attribute. Type: `boolean`	Default value
Prop hasAriaDisabled#	Description and type NOTE: Beta feature, may be changed or removed in the future Changes the native `disabled` attribute to `aria-disabled` to preserve focusability. This results in a semantically disabled button without the default browser handling of the disabled state. Use e.g. when a disabled button should have a tooltip. Type: `boolean`	Default value
Prop options#	Description and type Type: `never`	Default value
Prop buttonSize#	Description and type Typical sizing is `s`. Medium `m` size should be reserved for major features. Type: `"s" \| "m"`	Default value
Prop variant#	Description and type Defines the type of a button group, which renders visually and functionally different: default: arranges buttons in a horizontal row with optional gutter via `gutterSize` Type: `"default"`	Default value
Prop gutterSize#	Description and type Defines the gutter size between children buttons. Applies only when `variant="default"`. Type: `"s" \| "xs" \| "m" \| "l" \| "xl" \| "none"`	Default value
Prop isFullWidth#	Description and type Expands the whole group to the full width of the container. `EuiButton` children will stretch to fill the available space via their `fullWidth` prop. Type: `boolean`	Default value
Prop onChange#	Description and type Callback fired when a child button is selected. Returns the `id` of the clicked option. Applies only for `variant="selection"`. Type: `(id: string) => void`	Default value

EuiButtonGroupOptionsProps


Prop	Description and type	Default value
Prop legend#	Description and type A hidden group title (required for accessibility) Type: `string`	Default value Required
Prop options#	Description and type An array of EuiButtonGroupOptionProps Type: `EuiButtonGroupOptionProps[]`	Default value Required
Prop onChange#	Description and type Single: Returns the `id` of the clicked option and the `value` Multi: Returns the `id` of the clicked option Type: `((id: string, value?: any) => void) \| ((id: string) => void)`	Default value Required
Prop className#	Description and type Type: `string`	Default value
Prop aria-label#	Description and type Type: `string`	Default value
Prop data-test-subj#	Description and type Type: `string`	Default value
Prop css#	Description and type Type: `Interpolation<Theme>`	Default value
Prop isDisabled#	Description and type Controls the disabled behavior via the native `disabled` attribute. Type: `boolean`	Default value
Prop hasAriaDisabled#	Description and type NOTE: Beta feature, may be changed or removed in the future Changes the native `disabled` attribute to `aria-disabled` to preserve focusability. This results in a semantically disabled button without the default browser handling of the disabled state. Use e.g. when a disabled button should have a tooltip. Type: `boolean`	Default value
Prop buttonSize#	Description and type Typical sizing is `s`. Medium `m` size should be reserved for major features. `compressed` is meant to be used alongside and within compressed forms. Type: `"s" \| "m" \| "compressed"`	Default value
Prop isFullWidth#	Description and type Expands the whole group to the full width of the container. Each button gets equal widths no matter the content Type: `boolean`	Default value
Prop isIconOnly#	Description and type Hides the label to only show the `iconType` provided by the `option` Type: `boolean`	Default value
Prop color#	Description and type Any of the named color palette options. Do not use the following colors for standalone buttons directly, they exist to serve other components: accent warning Type: `"text" \| "accent" \| "accentSecondary" \| "primary" \| "success" \| "warning" \| "danger"`	Default value
Prop type#	Description and type Actual type is `'single' \| 'multi'`. Determines how the selection of the group should be handled. With `'single'` only one option can be selected at a time (similar to radio group). With `'multi'` multiple options selected (similar to checkbox group). Default for `type` is single so it can also be excluded Type: `"single" \| "multi"`	Default value
Prop name#	Description and type @deprecated No longer needed. You can safely remove this prop entirely @deprecated Type: `string`	Default value
Prop idSelected#	Description and type Styles the selected option to look selected (usually with `fill`) Required by and only used in `type='single'`. Type: `string`	Default value
Prop idToSelectedMap#	Description and type A map of `id`s as keys with the selected boolean values. Required by and only used in `type='multi'`. Type: `{ [id: string]: boolean; }`	Default value