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
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 typebutton - the other
<button>elements are of typesubmit - 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. |
Toggle group with icon
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
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.