Button Group

Button groups are a collection of related buttons.

Import#

import { ButtonGroup, ToggleButtonGroup } from '@volue/wave-react';

// you may also access context via hooks:
// import { useButtonGroupContext, useToggleButtonGroupContext } from '@volue/wave-react';

Button Group is a compound component that consists of multiple parts:

ButtonGroup: A container that groups buttons together.
ButtonGroup.Button: An individual group item, which composes Button component.

Toggle Button Group is a compound component that consists of multiple parts:

ToggleButtonGroup: A container that allows to use grouped items as a checkbox or radio buttons.
ToggleButtonGroup.Button: An individual group item, which composes Button component.

Examples#

Basic#

Button groups can be used to display set of actions that have a relationship in a "united" visual.

They are often used for various kinds of filtering or as a switch between different views.

Variants#

There are two visual variants, which set the visual priorities of the grouped buttons: outline and strong.

The default, outline variant is best for actions that are important but not primary in your app.

Use strong variant only to contain actions that are high emphasis.

Sizing#

Use size property to apply shared size for every button in a group. Available sizes are medium and small. See Button sizes.

Layout#

Use layout property to change how buttons are laid out.

inline (default) - the group acts as an inline-level box and the buttons are sized according to their content.
stretch - the group fills the container and the buttons are equal in width.

Disabled state#

Entire button group or isolated buttons can be disabled with the help of isDisabled property.

With icon buttons#

Groups can contain icon only buttons.

Please provide aria-label prop to support assistive technology (i.e. screen readers) or wrap the button with a tooltip.

Split buttons#

Use button group to create split buttons. Split buttons are useful for exposing a primary action that is most most commonly accessed while nesting secondary, less frequently used actions until needed. This makes them a nice pattern to helping a busy design feel more minimal.

Example below shows how a button in the group can be used to trigger a dropdown menu from the Menu component.

Split buttons can also be set in small size:

With overflow Menu#

Button groups work best with a limited set of items. If there are more than three items in the group, be thoughtful about how a long list of buttons might appear on small screens. Overflow Menu can be used when the button group is larger than its containing space or to preserve space.

Toggle button group#

ToggleButtonGroup is a specialized kind of button group that allows to toggle between or choose multiple items to make a selection.

In single type, the button group functions similarly to a radio group. Only one button in the group can be selected at a time.

Remember to provide aria-label for the toggle button group or linking it to an existing label via aria-labelledby.

For toggling between on/off states, consider using the Switch component.

In multiple type, the button group functions similarly to a group of checkboxes. Multiple buttons can be selected at the same time. Use only when a small list of options can be selected from.

Preselected toggle button group#

ToggleButtonGroup works in an uncontrolled way by default, meaning each ToggleButtonGroup component instance is responsible for managing selected value(s) internally. You can preselect toggle button group value or values (depending on the type) by using defaultValue property.

Controlled toggle button group#

As with many of our components, you can make the ToggleButtonGroup controlled, by passing your own state to value prop. onValueChange handler is called when the state of the toggle group changes, allowing you to sync state.

Accessibility features#

ButtonGroup adds role="group" to convey that the buttons are part of a group to users of assistive technologies.
ButtonGroup.Button with isActive prop set to true adds aria-current attribute to communicate currently active item to users of assistive technologies.
ToggleButtonGroup provides deep keyboard support via Roving Focus Group utility. Focus movement is managed using roving focus technique.
ToggleButtonGroup.Button uses role="radio" or role="checkbox" and keeps track of aria-checked attribute.

API Reference#

ButtonGroup#

Prop	Type	Default
`css`	`StitchesCss`	No default value
`isDisabled`	`boolean`	No default value
`variant`	`enum`	`"outline"`
`size`	`enum`	No default value
`layout`	`enum`	No default value
`orientation`	`enum`	`"horizontal"`

ButtonGroup.Button#

In addition to the props below, you can pass Button props with exception of size.

Prop	Type	Default
`as`	`enum`	`button`
`css`	`StitchesCss`	No default value
`isActive`	`string`	`false`
`isDisabled`	`boolean`	`false`

ToggleButtonGroup#

In addition to the props below, you can pass ButtonGroup props.

Prop	Type	Default
`type`*	`enum`	No default value
`value`	`string`	No default value
`defaultValue`	`string`	No default value
`onValueChange`	`function`	No default value
`value`	`string[]`	No default value
`defaultValue`	`string[]`	No default value
`onValueChange`	`function`	No default value
`aria-label`*	`string`	No default value

ToggleButtonGroup.Button#

In addition to the props below, you can pass Button props with exception of size.

Prop	Type	Default
`as`	`enum`	`button`
`css`	`StitchesCss`	No default value
`value`*	`string`	No default value
`isDisabled`	`boolean`	`false`