skip to content

Toggle group

A toggle group is a set of buttons that let users switch between different modes or views of the same content. For example, the same content in a graph view and a table view. One mode is active by default. Selecting another button changes how the content is presented.

Demo

<div class="u-mb-24">
{{> eds-c-toggle-group}}
</div>

Component anatomy

The toggle button group consists of:

  • a <form> with multiple <button> wrapped into a <fieldset>
  • the <button> bound to the selected option is a button of type button
  • the other <button> elements are of type submit
  • the <fieldset> contains a <legend> that contributes to the accessible name of the <button> group
  • selecting the [type="submit"] buttons will result in an action
  • selecting the [type="button"] button will not result in an action, its purpose is to show the current selected option

Usage

Relationship to other patterns

Component Use Differences
Toggle group button Switching between modes or views of the same content in place. Uses buttons. The active button represents the current display mode.
Tabs Moving between distinct sections or content areas, often at page or subpage level. Each tab identifies a separate panel or section rather than a different representation of the same content.
Radio buttons Choosing 1 option from a set, usually as part of a form or decision. Represents option selection and uses radio group semantics.
Standalone buttons Triggering an action such as submitting, saving or creating. Performs an action rather than changing an ongoing display mode.

When to use this component

Use the toggle group component when:

  • switching between 2 to 5 mutually exclusive views of the same content
  • displaying information in different formats, for example a graph and a table
  • changing the presentation in place without navigating to another page
  • modes that have equal importance where one is always active
  • situations where keeping modes visible makes switching quicker than using a menu

When not to use this component

Do not use the toggle group component when:

  • users need to navigate between distinct sections or URLs
  • you are collecting form data or asking users to choose an answer
  • you are helping users select settings where more than 1 item can be active
  • you need more than 5 modes or views

Button count

The component supports a minimum of 2 and a maximum of 5 buttons. If a use case requires more than 5 modes, teams should reconsider the content or use an alternative pattern.

Toggle group sizes

Size Description
Default For use when readability and prominence is required.
Small Uses smaller typography and reduced padding to work in confined spaces.
<div class="eds-l-stack" style="--eds-l-stack--gap: 1rem;">
{{#each .}}
<div>
{{> eds-c-toggle-group}}
</div>
{{/each}}
</div>

Toggle group with icon

<div class="eds-l-stack" style="--eds-l-stack--gap: 1rem;">
{{#each .}}
<div>
{{> eds-c-toggle-group}}
</div>
{{/each}}
</div>

Icons must support the meaning of the text label. Do not use icons on their own to represent different modes.

Content rules

  • use short labels of 1 to 3 words
  • use sentence case for all labels
  • name the mode, for example 'Graph' and 'Table', instead of 'Show graph'
  • give modes equal importance
  • use clear text labels, do not rely on colour or icons alone

How it works

Installation

To install the components, go to the get started guide for developers.

To use the Toggle group component, enter the following command in your Terminal:

npm install @springernature/elements

Styles

Import the styles of the toggle group component into your scss file:

@import '../path/to/@springernature/elements/components/eds-c-toggle-group';

Without JavaScript

Without JavaScript, choosing an option submits the form causing a page reload.

With JavaScript

When JavaScript is enabled, the component's behaviour can be enhanced by providing a jsHookValue in the component's configuration.
For example, "view-mode-toggle", and an onSubmitCallback function when initialising the component in your client-side JavaScript bundle.

Enhanced browsers use SubmitEvent.submitter to determine which button submitted the form.
The script then prevents the submission, moves the current option onto that button, and calls the onSubmitCallback with the submitter value, and the submitter element.
If the browser does not support the SubmitEvent API, then the default page reload behaviour applies.

Example context file

{
 "id": "viewModeToggleGroup",
 "action": "/viewMode",
 "method": "GET",
 "legend": "View mode",
 "name": "viewMode",
 "headingLevel": 3,
    "jsHookValue": "view-mode-toggle",
 "buttons": [
  {
   "label": "Compact",
   "id": "view-mode-compact",
   "value": "compact",
   "current": true
  },
  {
   "label": "Details",
   "id": "view-mode-details",
   "value": "details"
  }
 ]
}

Example client-side JavaScript

import EdsCToggleGroup from '@springernature/elements/components/eds-c-toggle-group/js/eds-c-toggle-group';

const toggleGroupElement = document.querySelector('[data-eds-c-toggle-group="view-mode-toggle"]');

new EdsCToggleGroup(toggleGroupElement, {
    onSubmitCallback: function(submitterValue, clickedButton) {
    // `submitterValue` is the selected button's value
 }
});

Demo

<div class="u-mb-24">
{{> eds-c-toggle-group}}
</div>

Configuration

To view the configurations for this component, go to the schema.

Name Type Description Required
id String Provides a unique identifier to differentiate between multiple instances of the component. Prefixes the legend and button IDs. ✅ Yes
action String Form action attribute value. ✅ Yes
method String Form method attribute value. ✅ Yes
headingLevel Number The heading level (2 to 6) for the fieldset's legend. ✅ Yes
legend String Text for the fieldset's legend. ✅ Yes
name String Name attribute for the radio inputs. ✅ Yes
buttons String Array of options for the toggle group input radios. Go to the button configuration ✅ Yes
currentSignifierText String The visually hidden text that tells assisted technology users the currently selected option. Default: , current. No
small Boolean Enables small toggle group size. No
jsHookValue String Use it to connect the markup with JavaScript. Such as to attach submit event handler to the form. For example, view-mode-toggle renders the data-eds-c-toggle-group="view-mode-toggle" attribute. No
dataAttributes Array Array of custom data attributes to add to the toggle group fieldset. No

Button configuration

Name Type Description Required
id String Provides a unique identifier to differentiate between buttons of multiple instances of the component. ✅ Yes
label String Text for the button label. ✅ Yes
value String The value of the input radio. ✅ Yes
current Boolean Whether or not the option associated with the button is currently selected. No
iconURL String URL of the icon to show on the button's label. No
dataAttributes Array Array of custom data attributes to add to the button. No

Help improve this page

If you have a question, idea, or suggestion to improve this component or guidance, post in the Ask Elements Teams channel.