`sp-action-group` delivers a set of action buttons in horizontal or vertical orientation while ensuring the appropriate spacing between those buttons. The `compact` attribute merges these buttons so that they are visually joined to clarify their relations
npm install @spectrum-web-components/action-groupsp-action-group delivers a set of action buttons in horizontal or vertical orientation while ensuring the appropriate spacing between those buttons. The compact attribute merges these buttons so that they are visually joined to clarify their relationship to each other and their distance from other buttons/groups.
``
yarn add @spectrum-web-components/action-group
Import the side effectful registration of via:
`
import '@spectrum-web-components/action-group/sp-action-group.js';
When looking to leverage the ActionGroup base class as a type and/or for extension purposes, do so via:
`
import { ActionGroup } from '@spectrum-web-components/action-group';
`html demo`
`html demo`
`html demo`
`html demo`
`html demo`
An will manage a selected property that consists on an array of the children that are currently selected. A change event is dispatched from the element when the value of selected is updated. This event can be canceled via event.preventDefault(), after which the value of selected will be returned to what it was previously.
When a selection can be made, it is a good idea to supply the group of options with accessible text that names the group of buttons. This can be done in a non-visual way via the label attribute of the element. You can also associate the to a second, visible DOM element via the aria-labelledby attribute or, when available, via the for attribute on the second element to make the association in the other direction.
An will manage its children as "radio buttons" allowing the user to select a _single_ one of the buttons presented. The children will only be able to turn their selected value on while maintaining a single selection after an initial selection is made.
`html`
emphasized
label="Single Selection Demo Group"
>
Button 1
Longer Button 2
Short 3
An will manage its children as "checkboxes" allowing the user to select a _multiple_ of the buttons presented. The children will toggle their selected value on and off when clicked successively.
`html`
emphasized
label="Multiple Selection Demo Group"
>
Button 1
Longer Button 2
Short 3
The selected property represents the selection state within a button group. This property can be managed either by the component or by the user. Passing in an array of button values will make a controllable component. Though selected would more commonly be set via Javascript expressions (i.e. ), it is also possible to set selected as a JSON string.
`html`
By default, an will select any button passed into selected. Afterwards, .selects controls how button values are added to the selection state. For example, if .selects is not specified when selected is set, any further interaction will result in no change to the selection.
`html`
Similarly, if selected contains more than one button value, but selects = "single", then those initial buttons will be highlighted, but further interaction will result in radio-button functionality.
`html`
By default, an will organize its child buttons horizontally and the delivery of those buttons can be modified with the compact, emphasized, or quiet attributes.
`html`
Button 1
Longer Button 2
Short 3
Button 1
Longer Button 2
Short 3
The use of the vertical attribute instructs the element to organize its child buttons vertically, while accepting the same compact, emphasized, and quiet attributes as modifiers.
`html`
Button 1
Longer Button 2
Short 3
Button 1
Longer Button 2
Short 3
The justified attribute will cause the element to fill the available horizontal space and evenly distribute that space across its child button elements.
`html`
Button 1
Longer Button 2
Short 3
Button 1
Longer Button 2
Short 3
The accessibility role for an element depends on the manner in which items are selected. By default, will have role="radiogroup", because it manages its children as a "radio group", while or will have role="toolbar", which makes sense for a group of buttons or checkboxes between which one can navigate using the arrow keys.
When more than one elements are combined together with in a toolbar, the role attribute for or should be overwritten using role="group" or role="presentation", so that toolbars are not nested, as demonstrated in the following example of a hypothetical toolbar for formatting text within a rich text editor:
`html
role="toolbar"
style="height: 32px; display: flex; gap: 6px"
>
selects="multiple"
role="group"
compact
emphasized
>
style="align-self: stretch; height: auto;"
vertical
>
selects="single"
compact
emphasized
>
>
style="align-self: stretch; height: auto;"
vertical
>
selects="multiple"
role="group"
compact
emphasized
>
value="bulleted"
onclick="
/ makes mutually exclusive checkbox /
this.selected &&
requestAnimationFrame(() => this.parentElement.selected = []);
this.parentElement.selected = [];
"
>
value="numbering"
onclick="
/ makes mutually exclusive checkbox /
this.selected &&
requestAnimationFrame(() => this.parentElement.selected = []);
this.parentElement.selected = [];
"
>
style="align-self: stretch; height: auto;"
vertical
>