-
Notifications
You must be signed in to change notification settings - Fork 160
Button Group Specification
The igx-buttongroup groups a series of [igxButton]s together, exposing
features such as layout and selection.
The <igx-buttongroup> must support the following features out-of-the-box.
- Supports slotting of
[igxButton](s) inside it. - Support for horizontal and vertical layout orientation for the slotted
[igxButton](s) inside it. - Support for controlling the type of selection; single (default), single required 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.
- Supports sizing the underlying buttons through a CSS variable.
- Follows the WAI-ARIA guidelines as closely as possible.
Developer stories:
As a developer I expect to be able to:
- create a button group with slotted
[igxButton](s). - control the layout and orientation of elements projected into the group.
- set a disabled attribute so that the control and its children can't be modified or interacted with.
- control the selection behavior (single/single-required/multiple).
- set/get the current selection either through an attribute on the button group or through attribute(s) on its children.
End-user stories:
As an end-user I expect to be able to:
- have distinct visual indication reflecting the different states the control is in (selected, disabled, etc.)
- interact with the control with keyboard and with a pointer device
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 igx-buttongroup comes fully styled in accordance with the currently active theme.
Events are emitted when a user interacts with an underlying [igxButton], that is either through a pointer click or a Space/Enter key being pressed on a child button.
Changing the selected property of an underlying [igxButton] is reflected in the selection state of the group. However that operation does not emit an event.
On initial render any selected attributes present on the underlying buttons will take priority over the selected-items attribute of the button group.
On initial render if the selection mode is either single or singleRequired and there are multiple selected buttons underneath, only the last one will remain selected.
When the selection mode is set to singleRequired, the button group behaves similar to a radio group. That is once there is a selected button, it cannot be deselected through user interactions.
When the selection mode is set to singleRequired, interacting with the already selected button will not emit any events.
Runtime changes to the selection property of the group will remove the current selection state of the component.
No specific points are applicable for localization.
No additional implementation is required.
| Property | Type | Default | Description |
|---|---|---|---|
disabled |
boolean |
false |
Disables all buttons inside the group |
alignment |
horizontal | vertical |
horizontal |
Get/Set the orientation of the buttons in the group |
selectionMode |
single | singleRequired | multi |
single |
Get/Set the selection mode for the group |
selectedButtons |
IgxButtonDirective[] |
- | Gets the selected buttons in the group |
buttons |
IgxButtonDirective[] |
- | Gets all buttons in the group |
| Method | Type | Description |
|---|---|---|
selectButton |
(index: number): void |
Selects a button by its index |
deselectButton |
(index: number): void |
Selects a button by its index |
| Name | Description |
|---|---|
selected |
Fired when a button is selected. |
deselected |
Fired when a button is unselected. |
Automation
- should initialize a button group
- 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
In order for assistive technologies (such as screen readers) to convey that a series of buttons is grouped, the igx-buttongroup should have by default its role set to group.
The component should work in a Right-To-Left context without additional setup or configuration.
While virtually any element can be slotted inside the igx-buttongroup, it only operates over [igxButton](s).