A toggle button is a special type of button that conveys a pressed or non-pressed state; this state is conveyed programmatically via the aria-pressed attribute. They can be used in single-select or multi-select groups.

These buttons, like all buttons, should NOT contain structural elements, such as headings or lists.

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

Minimal Layout

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.

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--list-layout modifier to the toggle button.

List Toggle Button with Title

List Toggle Button with Title and Subtitle

A subtitle can be added via toggle-button__subtitle block.

List Toggle Button with Title and Multi-line Subtitle

To have a multi-line subtitle, you may use a single <p> tag that has longer text or a maximum of two separate <p> tags with shorter text inside the toggle-button__subtitle block.

List Toggle Button with Icon, Title, and Subtitle

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

List Toggle Button with Image, Title, and Subtitle

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.

Using an Image Element

TitleSubtitle

Using a Contained CSS Background Image

Using a Cover CSS Background Image

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--gallery-layout modifier to the toggle button.

Gallery Toggle Button with Image

To add an image to a toggle button, you can use the toggle-button__image-container block.

TitleSubtitle

Gallery Toggle Button Responsive Adjustments

Toggle buttons have a mininum and maximum width and are meant to be fluid between those boundaries. If using these buttons separately, you will need to set up their combined high-level layouts on your own. In these examples, their widths are artificially/manually set to various widths to demonstrate how the buttons undergo responsive adjustments.

The image used in these buttons will shrink/grow responsively in width and height based on the overall button width.

Resonsive Images Using Image Element

Minimum ButtonSubtitle260px Sized ButtonSubtitle342px Sized ButtonSubtitle

Responsive Images Using CSS Background-Image

These buttons use background-size: contain; for background image scaling/filling.

These buttons use background-size: cover; for background image filling the alloted space. The following buttons have the background image positioning using background-position-y: 20%; . Depending on your specific image, you may also need to adjust the background positioning along the x and y axis to ensure the main focal point remains visible and centered in your implementation.

Gallery Toggle Button with Icon

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

Disabled Toggle Button

Toggle buttons may be disabled with disabled or aria-disabled="true" .