• Button group and toggle button specification
  • Owned by
    • Requires approval from
    • Signed off by
    • Revision history
  • Toggle button
    • Overview
      • Acceptance criteria
    • User stories
    • Functionality
      • End-user experience
      • Developer experience
        • Basic usage
        • With slotted content
      • Localization
      • Keyboard navigation
    • API
      • Properties
      • Methods
      • Slots
      • CSS Shadow Parts
    • Test scenarios
    • Accessibility
      • ARIA
      • RTL support
    • Assumptions and limitations
  • Button group
    • Overview
    • Acceptance criteria
    • User stories
    • Functionality
      • End-user experience
      • Developer experience
        • Default initialization
        • Vertical orientation
        • Initialization with multiple selection enabled
        • Initial selection through child
        • Initial selection through selected-items attribute
      • Localization
      • Keyboard navigation
    • API
      • Properties
      • Events
      • Slots
      • CSS parts
    • Test scenarios
    • Accessibility
      • ARIA
      • RTL
    • Assumptions and limitations

Team name: Astrea

Developer name: Riva Ivanova

Designer name: Marin Popov

• Radoslav Karaivanov | Date: 2023-09-28
• Svilen Dimchevski | Date:

• Radoslav Mirchev | Date:
• Damyan Petev | Date:

An <igc-toggle-button> wraps a native button element and exposes additional value and selected properties. It is used in the context of an <igc-button-group> to facilitate the creation of group/toolbar like UX behaviors.

The igc-toggle-button:

• must support user provided slotted content.
• must expose a disabled property which is controlled through an attribute and must have a visual state reflecting its disabled state.
• must expose a selected property which is controlled through an attribute and must have a visual state reflecting its selected state.
• must expose a value property which is controlled through an attribute.
• must support vertical sizing based on its parent igc-button-group or by setting an explicit CSS variable on the element itself.
• must follow the WAI-ARIA guidelines as closely as possible and be accessible with both keyboard and pointer devices.

Developer stories:

As a developer I expect to be able to:

• set a selected attribute so that the component can be programmatically initialized or updated based on external factors
• set a value attribute so that I can use that value when an end-user interacts with the component
• slot content in the exposed component slots so I can achieve customization in scenarios where additional visual indication is needed or certain design guidelines are required

End-user stories:

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

• have distinct visual indication reflecting the current state of the element (selected, disabled)
• interact with the control with keyboard and pointer devices

Design hand-off

The <igc-toggle-button> is used in combination with the <igc-button-group> component to achieve toolbar like UX.

<igc-button-group>
  <igc-toggle-button value="1">First</igc-toggle-button>
  <igc-toggle-button value="2">Second</igc-toggle-button>
  <igc-toggle-button value="3">Third</igc-toggle-button>
</igc-button-group>

Emulating a text formatting toolbar:

<igc-button-group selection="multiple">
  <igc-toggle-button aria-label="Bold" value="bold">
    <igc-icon name="bold"></igc-icon>
  </igc-toggle-button>
  <igc-toggle-button aria-label="Italic" value="italic">
    <igc-icon name="italic"></igc-icon>
  </igc-toggle-button>
  <igc-toggle-button aria-label="Underline" value="underline">
    <igc-icon name="underline"></igc-icon>
  </igc-toggle-button>
</igc-button-group>

No specific points are applicable for localization.

No additional implementation is required.

Automation

1. The action button is correctly rendered.
2. The action button is correctly initialized with its default component state.
3. The action button passes automated WAI-ARIA tests.
4. The action button disabled state can be toggled and is correctly reflected.
5. The action button selected state can be toggled and is correctly reflected.

• <igc-toggle-button> transfers its aria-label attribute, if present, to the native button element.
• <igc-toggle-button> sets the aria-pressed attribute value of the underlying native button based on its current selected state.

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

None applicable.

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

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

1. Supports slotting of igc-toggle-button(s) inside it.
2. Support for horizontal and vertical layout orientation for the slotted igc-toggle-button(s) inside it.
3. Support for controlling the type of selection; single (default), single required and multiple.
4. Support for setting and managing selection state, both declaratively (attribute) and through API (property).
5. Support for setting the disabled state of all projected buttons under the component.
6. Supports sizing the underlying buttons through a CSS variable.
7. 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 igc-toggle-button(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 igc-button-group comes fully styled in accordance with the currently active theme.

Design hand-off

Events are emitted when a user interacts with an underlying igc-toggle-button, 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 igc-toggle-button 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 single-required and there are multiple selected buttons underneath, only the last one will remain selected.

When the selection mode is set to single-required, 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 single-required, 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.

<igc-button-group>
  <igc-toggle-button value="left">Left</igc-toggle-button>
  ...
</igc-button-group>

<igc-button-group alignment="vertical">
  <igc-toggle-button value="left">Left</igc-toggle-button>
  ...
</igc-button-group>

<igc-button-group selection="multiple">
  <igc-toggle-button value="left">Left</igc-toggle-button>
  ...
</igc-button-group>

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

<igc-button-group selected-items='["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>

No specific points are applicable for localization.

No additional implementation is required.

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 igc-button-group 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 igc-button-group, it only operates over igc-toggle-button(s).