Pharos
JSTOR's Design System
 Getting started Help FAQs DocumentationDevelopment GitHub JSTOR LogosTypographyColorImageryIconographyElevationVoice and toneJSTOR termsWeb elementsGrammar and styleEditing checklistAlertButtonBreadcrumbCheckboxCheckbox groupCoach MarkComboboxDropdown menuDropdown menu navFooterHeaderHeadingIconImage cardInput groupLayoutLinkLoading spinnerModalMultiselect dropdownPaginationPillPopoverProgress barRadio buttonRadio groupSelectSheetSidenavSwitchTableTabsToastTooltipText inputTextareaToggle button groupOverviewAlias colorsGlobal colorsFont familyFont sizeFont weightLine heightElevationRadiusSpacingTransitionsType scaleType styles
Skip to main navigation
Toggle Button Group
Toggle button groups present related actions together to allow the user to select from mutually exclusive options.
Example
GalleryList

See live code examples in Storybook
Usage

Within a toggle button group, only one option can be selected at a time. Selecting one option deselects all others.

Use a toggle button group as a switch between different views. For example, use the component to allow users to switch between a list view and gallery view.

Best practices
Dos
  • Group items within a toggle button group that are related and have a logical connection to each other
  • Think about whether your toggle button group needs text and an icon, text only, or an icon only
  • Use short and concise text for the labels (if applicable)
  • Place the toggle button group in close proximity (ideally just above) to the area it controls
Don'ts
  • Don't group items that aren't clearly related
  • Don't use an icon-only toggle if the actions aren't clearly understood
  • Don't use a toggle button group if there are more than three options
  • Avoid wrapping the toggle button group onto more than a single row.
Content guidelines

If using labels, they should be concise and descriptive, using no more than three words.

States Default

Indicates that the user can interact with the button.

Selected

Indicates that the button is selected.

Disabled

Indicates that the user is unable to interact with the button.

Variants Icon + Text
GalleryList
Text only
GalleryList
Icon only
Accessibility Relevant WCAG guidelines
  • 1.3.1 Info and Relationships A
Code expectations

  • There is a role="group" attribute on the parent element

    • If the toggle button group is part of a toolbar use role="toolbar"

  • Use the semantic <button> on all grouped elements under the parent element

  • If the button needs additional information in order to be understood by assistive technologies, use an aria-label attribute to convey this information

Expected actions Screen reader
  • Reads: "Button name (or aria-label), button"
Keyboard
  • Tab: advances to the next element
  • Shift + Tab: goes to the previous element
  • Enter or Space: activates the element in focus