The Toggle Button Group is a group of single or multi-select toggle buttons providing a visual emphasis on the available selectable choices.

Intended Use of Toggle Button Group

Toggle Buttons inside Toggle Button Group are intended to be input controls. They are ment to be used for users to make selection(s) that can be used for additional actions. For example, they can be used to storing the selection(s) and using JavaScript to include the information in a form submission.

Toggle Buttons are NOT to be used for the purposes of navigation.

The component allows for single or multiple selections based on need. However, when using Skin by itself you will need to have your own JavaScript to establish those rules based on the specific needs for each implementation context.

Effort was taken in these docs to provide a good amount of helpful information. Since this component has an atomic piece ( Toggle Button ), there may be some information crossover. Though efforts were taken to isolate the documentation for this parent component, at various touchpoints between the two components, there may be some redundancy. In other portions, where immediate information appears to be missing here, that information may reside in its child component. Please refer to Toggle Button docs in these situations.

Accessibility

The preferred implementation for accessibility includes an on-screen heading and the list associated with the heading (a). The second option is an off-screen heading with the same association (b). The third is to use the label directly on the list element (c).

On-screen Heading with Associated List (a - preferred)

Off-screen Heading with Associated List (b)

This implementation is identical to option (a), except the heading is off-screen using the clipped class.

Interaction Variations of Toggle Button Groups

There are three different types of toggle button groups that may be utilized based on interaction need.

1. Multi-select: this is a freeform implementations in which the user can toggle and untoggle any button.
2. Single-select Optional: only one button can be toggled on at any given time and the user CAN untoggle that one button.
3. Single-select Required: only one button can be toggled on at any given time and the user CANNOT untoggle that one button.

If you're using Skin outside of a JavaScript framework, you will need to write your own js code to accomplish these interactivity cases.

It's generally good practice to use delegated event handlers that allow you to set up a a single event handler for the group of buttons instead of on every button.

The following examples use an HTML attribute to disitnguish the interaction variations. Using data-selection-type . For the associated js please see /docs/src/js/main.js (TOGGLE-BUTTON-GROUP section) for an example on how the implementation may be accomplished.

Multi-select

The Multi-select variation is the default so nothing additional needs to be specified in the markup.

Single-select Optional

In this example of the Single-select Optional variation, data-selection-type="single-optional" is used to split off the variation interactivity. This option allows for only one selection, so toggling additional buttons will simply switch the toggled button and retain only one toggled button.

Single-select Required

In this example of the Single-select Optional variation, data-selection-type="single-required" is used to split off the variation interactivity. This option allows for only one selection. However, unlike the single-select optional variation, this variation enforces the required single selection so the toggled button cannot be untoggled.

Responsive Out of the Box

Toggle Button Group is responsive out of the box. The buttons will responsively shrink and stretch the specific type of buttons inside and attempt to fit the buttons nicely within the container at any and all screen sizes.

We use display: grid to create a predefined allotted number of button slots per breakpoint. We also use container queries to modify how many slots should be available per breakpoint. This allows buttons to shrink/stretch the predefined number of buttons at each breakpoint with a fallback to media queries for unsupported browsers.

The responsive rules around how many toggle buttons appear on a single line before wrapping into a new line have all been predefined and baked into the component, so developers don't need to provide anything else to have an optimal responsive toggle button layout at various screen sizes.

In the demo below, drag the range to see the responsive rules in action and how the fluid Toggle Buttons work.

Exception Cases for Preferred Number of Toggle Buttons Per Line

The buttons inside the Toggle Button Group are automatically responsive and have predefined rules around how many Toggle Buttons will display on a line before wrapping to the next line. However, on some rare occasions, developers may need to revise those rules based on how a Toggle Button Group works in their specific use case. For example, when the number of buttons is deterministic and known. In those instances, using various attributes mapped to each breakpoint will allow the rules to be honored by the component. At those specific breakpoints, the number of buttons specificed will be displayed.

Here's a specific example. Suppose we know we're going to have 6 buttons total and we'd like to have perfect visual balance in the UI. We may add the following html attributes/modifiers to .toggle-button-group to achieve that:

• data-columns-xs="2" to force 2 toggle buttons on the same line so we'd have 3 balanced lines of buttons at the XS breakpoint or at 320px + width.
• data-columns-sm="3" to force 3 toggle buttons on the same line so we'd have 2 balanced lines of buttons at the SM breakpoint or at 512px + width.
• data-columns-md="6" to force all 6 toggle buttons on the same line at the MD breakpoint or at 768px + width.
• data-columns-xl="8" to force all 8 toggle buttons on the same line at the XL breakpoint or at 1280px + width.

Here's that use case in action. Drag the range to see the effects of the attribute settings at various container widths.

Layouts

There are various layouts that can be used based on the specific needs at implementation. The implied theme (needs no modifier), is the minimal layout. For more information about types of layouts, refer to the Toggle Button component. The examples below will highlight various layouts.

A toggle button group can have one of three different layouts: minimal (default), list or gallery.

Layout Modifiers

Toggle Button Group has top-level modifiers that will apply to the Toggle Buttons inside. When using Toggle Buttons inside Toggle Button Group make sure you do NOT specify each Toggle Button layout modifier. Instead, top-level layout modifiers will be sufficient to create the layout you want.

Minimal Layout (default)

The default, minimal toggle button should be used when the contents are single-line and very short, as in shoe sizing, for example. This layout is geared more towards allowing the display of many more options and maximizing screen real estate.

NOTE: All toggle button examples utilize JavaScript to toggle the aria-pressed state of the button.

In this example, the container housing the Toggle Button Group is artificially limited to 500px to demonstrate how the buttons will wrap after the specific columns (in this case, 3). Feel free to reduce/expand the container width in dev console to see how the columns will react.

List Layout

List layout should be used when it's desired to have wider horizontal buttons. These are more easily stackable on narrower screens.

You may use this layout by adding the toggle-button-group--list-layout modifier to the toggle button group.

List Layout Toggle Button Group with Title

List Layout Toggle Button Group with Subtitles (multiple buttons toggled on)

List Layout Toggle Button Group with Icons

List Layout Toggle Button Group with Images

To add an image to a toggle button, you can use the toggle-button__image-container block using an <img> or as a css background image.

Select Payment Option

List Layout Toggle Button Group with CSS Images

Select Payment Option

Gallery Layout

Gallery layout should be used when there will be fewer buttons (as larger buttons take up more screen real estate) and it's desired to have a more vertical/square implementations with more emphasis on graphical elements (images/icons). As such, since the purpose of gallery layout buttons is to exentuate graphical elements, a graphical element (icon or image) is typically required in gallery layout buttons.

You may use this layout by adding the toggle-button-group--gallery-layout modifier to the toggle button group.

Gallery Layout Toggle Button Group with Images

The image used in these buttons will shrink/grow responsively in width and height based on the overall button width being respectful of their boundary limitations. Where those boundaries are in danger of being crossed, the layout will wrap accordingly.

Gallery Layout Toggle Button Group with CSS Images

Besides using an <img> , you may also use CSS images that can provide more flexibility in filling more of the space reserved for images.

These images will change in size responsively both horizontally and vertically based on the size of the button itself, available space allowed by the container and their minimum and maximum size limitations.

The examples below have various different implementations of CSS images. The first is a CSS Profile Image button with background-size: contain that will display the image as is and fit the entire image in the container. The second is a CSS Profile Image button with background-size: cover that will display the image to fill as much of the space of the container as possible clipping out the remaining portions of the image that fall outside. With that method, you can also provide guidance for fine-tuning the image positioning to move the focal point into the center of the container. In that example, background-position: center 15%; is used to move the focal point (person with camera) into the center of the frame.

Gallery Layout Toggle Button Group with Icons

Typically, one would use either all image buttons or all icon buttons in a Toggle Button Group.

To add an icon to a toggle button, you can use the toggle-button__icon block.