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.

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
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