Button Group Specification

Button group specification

Owned by

Team Name: Astrea

Developer Name: Riva Ivanova

Designer Name: Marin Popov

Requires approval from

Peer Developer Name | Date:
Design Manager Svilen Dimchevski| Date:

Signed off by

Radoslav Mirchev| Date:
Damyan Petev | Date:

Overview

The igc-button-group groups a series of buttons together, exposing features such as layout and selection. The component makes use of igc-toggle-button.

Acceptance criteria

The igc-toggle-button wraps a native button element and exposes additional value and selected properties.

The igc-button-group must support the following features out-of-the-box.

Support for slotting of user provided content (igc-toggle-button components, text, etc.) inside it.
Each child button should support projecting user provided content.
Support for horizontal and vertical layout orientation for the slotted buttons inside it.
Support for controlling the type of selection; single (default) and multiple.
Support for setting and managing selection state, both declaratively (attribute) and through API (property).
Support for setting the disabled state of all projected buttons under the component.
Support sizing through a CSS variable.

⚠️ R.K.: Discuss whether the group should control the sizing of its children or they can override it
Follows the WAI-ARIA guidelines as closely as possible.

User stories

Developer stories:

As a developer I expect to be able to:

create a button group with slotted buttons
control the layout and orientation of elements projected into the group
set a disabled state as an attribute on either the button group or on its children so that the control and its children can't be modified or interacted with
control the selection behavior (single/multiple)
set/get the current selection either through an attribute on the button group or through attribute(s) on its children
set a value attribute on the toggle buttons in the group so that they can be programmatically initialized or updated.

End-user stories:

As an end-user I expect to be able to:

have distinct visual indication reflecting the different states the control and its children are in (selected, disabled, etc.)
interact with the control with keyboard and with a pointer device

Functionality

The end-users must be able to select button(s) from the group, through pointer device and keyboard, based on the selection mode of the component. The igc-button-group comes fully styled in accordance with the currently active theme.

End-user experience

Design hand-off

Developer experience

While any element may be slotted inside the igc-button-group, only igc-toggle-buttons provide the additional functionality one would expect. The selection behavior works with projected igc-toggle-buttons.

The button group reacts when a child button has its selected attribute changed, reflecting the new selection state. It does not emit an event in that case.

Default initialization

<igc-button-group>
  <igc-toggle-button value="left">Left</igc-toggle-button>
  <igc-toggle-button value="center">Center</igc-toggle-button>
  <igc-toggle-button value="right">Right</igc-toggle-button>
</igc-button-group>

Vertical orientation

<igc-button-group alignment="vertical">
  <igc-toggle-button value="left">Left</igc-toggle-button>
  <igc-toggle-button value="center">Center</igc-toggle-button>
  <igc-toggle-button value="right">Right</igc-toggle-button>
</igc-button-group>

Initialization with multiple selection enabled

<igc-button-group multiple>
  <igc-toggle-button value="left">Left</igc-toggle-button>
  <igc-toggle-button value="center">Center</igc-toggle-button>
  <igc-toggle-button value="right">Right</igc-toggle-button>
</igc-button-group>

Initial selection through child

<igc-button-group>
  <igc-toggle-button value="left" selected>Left</igc-toggle-button>
  <igc-toggle-button value="center">Center</igc-toggle-button>
  <igc-toggle-button value="right">Right</igc-toggle-button>
</igc-button-group>

Initial selection through attribute

<igc-button-group selection='["left"]'>
  <igc-toggle-button value="left">Left</igc-toggle-button>
  <igc-toggle-button value="center">Center</igc-toggle-button>
  <igc-toggle-button value="right">Right</igc-toggle-button>
</igc-button-group>

⚠️ T.H.: Decide about the priority of the selection - at group level or at button level is higher?

Localization

No specific points are applicable for localization.

Keyboard navigation

No additional implementation is required.

⚠️ R.K.: One can say keyboard navigation may follow the behavior of a radio group (roving tabindex). Personally, I am against implementing it as such.

API

Properties

`IgcToggleButtonComponent`

classDiagram

IgcButtonBaseComponent..|>IgcToggleButtonComponent : "fab" is strange in the context of group

class IgcButtonBaseComponent {
  type: 'button' | 'reset' | 'submit'
  disabled: boolean
  ...
  focus(options?: FocusOptions): void
  blur(): void
  click(): void
}

class IgcToggleButtonComponent {
  +selected: boolean
  +value: string
}

`IgcButtonGroupComponent`

Property	Attribute	Reflected	Type	Default	Description
`multiple`	`multiple`	Yes	`boolean`	`false`	Enables selection of multiple buttons
`disabled`	`disabled`	Yes	`boolean`	`false`	Disables all buttons inside the group
`alignment`	`alignment`	Yes	`"horizontal" \| "vertical"`	`"horizontal"`	Sets the orientation of the buttons in the group
`selection?`	`selection`	No	`string[]`	`[]`	Gets/Sets the currently selected buttons (their values)

Events

Name	Description	Cancelable	Parameters
`igcChange/igcSelect`	Emitted when the selection state of the underlying buttons is changed through user interaction	`true`	`{ button: IgcToggleButtonComponent, value: string \| undefined }`

⚠️ R.K.: The event is emitted when a user interacts with `igc-toggle-button`s only

Slots

Name	Description
(default)	Renders igc-toggle-button component.

CSS parts

Name	Description

Test scenarios

should initialize a button group with toggle buttons
should initialize a button group with initial selection state through attribute (single/multiple)
should initialize a button group with initial selection state through children selection attribute (single/multiple)
should be able to update selection state through group's selection property
should be able to update selection state through the selected property of its children
should be able to select only a single button through UI when selection is single
should be able to select multiple buttons through UI when selection is multiple
should not be able to interact through UI when the group is disabled
event is correctly emitted on user interaction
passes automated WAI-ARIA tests
should set the selection to be the last selected button if multiple buttons are selected (single mode)
should clear the selection when changing the selection mode

Accessibility

ARIA

<igc-toggle-button> transfers the aria-label attribute to the wrapped native button element if applicable.
<igc-toggle-button> apples the appropriate aria-selected attribute value based on its selected attribute.
igc-button-group should have by default its role set to group.

RTL

The component should work in a Right-To-Left context without additional setup or configuration.

Assumptions and limitations

The component assumes it will have only igc-toggle-button elements as its children. Slotting anything else is possible but is ignored by the component when managing state and behavior.

As such setting a disabled state will affect only those elements. Furthermore, selection works ONLY with igc-toggle-button.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly