Toggle button

The standalone ToggleButton enables users to seamlessly switch between two distinct states, such as on/off or active/inactive.

Include both icons and text within toggle buttons to visually reinforce the intent of the options or when additional context can aid decision-making, such as selecting a document type or a text style.

• To reduce visual noise and mitigate alignment issues, use icons in toggle button labels consistently across all options in a toggle button group.
• Icons should only be placed to the left of the text in order to further describe the action, placing to the right would suggest an onward direction or movement.

You can use toggle buttons with icons only. Use an icon-only button when screen space is limited, and the icon is easily understandable.

• Self-explanatory icons: An icon-only toggle button should be intuitive, ideally using well-known recognisable symbols. If the purpose of the button isn’t clear from the icon alone, add a label.
• Icon switching: Consider switching icons based on the selection state of the toggle button, for instance by switching between outline and solid icon variants or active/inactive icons, such as locked and unlocked.
• Accessibility: Provide an accessible label for each toggle button.
• Tooltips: Use Tooltip to provide additional context for each toggle button.

You can configure toggle buttons to only display text if you can’t identify a suitable or intuitive icon.

• Label switching: Consider changing the text on the toggle button to complement its selected state. If the label does change based on the selected state, ensure any changes to the button's width do not adversely affect alignment.

In addition to neutral, toggle button has four other sentiments available — accented, positive, caution and negative. You can set this using the sentiment prop. Sentiments are based on the following recommendations:

• Accented: Allows greater visual emphasis to be placed on actions.
• Positive: Indicates actions that result in positive outcomes.
• Caution: Alerts users to potential consequences that may arise from taking an action.
• Negative: Indicates actions that lead to negative outcomes.

There are two different appearances that can be applied to the selected state of a toggle button: solid and bordered. By default, toggle buttons are set to solid. You can change the appearance to bordered using the appearance prop.

• Visual hierarchy: Changing the appearance to bordered can reduce the prominence of the toggle button when in a selected state.

You can disable toggle buttons if required by context or user permissions using the disabled prop. Disabling a toggle button will prevent the user from interacting with it and suppresses all functionality.

A ToggleButtonGroup allows users to make a mutually exclusive selection from a set of related commands—with only one option selected at a time.

• Number of options: A toggle button group should always contain two or more options related by function or context. Examples include text alignment (left, center, right, justified) or risk level (high, medium, low).
• Text and icon: Use text description in addition to or instead of an icon if the options in the toggle button group are high priority. Users will be less likely to overlook the options.

By default, a toggle button group has horizontal alignment. To present the options in a stacked layout, orientate the group vertically using the orientation=”vertical” prop.

When oriented vertically, the group will resize to fit the longest toggle button, with all other buttons in the group extending to fill the same width.

Setting the toggle button group as read-only using the readOnly prop will render the toggle button group in a non-interactive state and with read-only styles. This is useful for scenarios where users need to view the current selection, but may not have the right permissions to change it.

If a toggle button is in a selected state within a read-only toggle button group, it will retain its visual style to indicate selection and remain focusable via keyboard navigation, ensuring that users can perceive the selection through assistive technologies.

Disabling a toggle button group using the disabled prop will suppress functionality for all buttons within it.

• Disable or Read-Only: Disable the group when it is not relevant or permitted in the current user flow; in this state, it will not be focusable for screen readers. Set the group to read-only when it is important for the user to know which option is currently selected. When set to read-only, the selected button will still be focusable for screen readers but will be indicated as non-interactive.

Sentiment can be set on a toggle button group or individual buttons within a group. Setting sentiment on individual buttons allows for a mixed group.

Set sentiment by using the sentiment prop, either on the group as a whole or on individual toggle buttons within the group.

The appearance prop allows you to define the selected appearance for all buttons in the toggle button group as either solid or bordered.

• Set Appearance on the Group: Although it is possible to mix sentiment within a group, it is not recommended to do the same with appearance as it can lead to visual inconsistency and diminish clarity for the user.

The standalone ToggleButton enables users to seamlessly switch between two distinct states, such as on/off or active/inactive.

Include both icons and text within toggle buttons to visually reinforce the intent of the options or when additional context can aid decision-making, such as selecting a document type or a text style.

• To reduce visual noise and mitigate alignment issues, use icons in toggle button labels consistently across all options in a toggle button group.
• Icons should only be placed to the left of the text in order to further describe the action, placing to the right would suggest an onward direction or movement.

You can use toggle buttons with icons only. Use an icon-only button when screen space is limited, and the icon is easily understandable.

• Self-explanatory icons: An icon-only toggle button should be intuitive, ideally using well-known recognisable symbols. If the purpose of the button isn’t clear from the icon alone, add a label.
• Icon switching: Consider switching icons based on the selection state of the toggle button, for instance by switching between outline and solid icon variants or active/inactive icons, such as locked and unlocked.
• Accessibility: Provide an accessible label for each toggle button.
• Tooltips: Use Tooltip to provide additional context for each toggle button.

You can configure toggle buttons to only display text if you can’t identify a suitable or intuitive icon.

• Label switching: Consider changing the text on the toggle button to complement its selected state. If the label does change based on the selected state, ensure any changes to the button's width do not adversely affect alignment.

In addition to neutral, toggle button has four other sentiments available — accented, positive, caution and negative. You can set this using the sentiment prop. Sentiments are based on the following recommendations:

• Accented: Allows greater visual emphasis to be placed on actions.
• Positive: Indicates actions that result in positive outcomes.
• Caution: Alerts users to potential consequences that may arise from taking an action.
• Negative: Indicates actions that lead to negative outcomes.

There are two different appearances that can be applied to the selected state of a toggle button: solid and bordered. By default, toggle buttons are set to solid. You can change the appearance to bordered using the appearance prop.

• Visual hierarchy: Changing the appearance to bordered can reduce the prominence of the toggle button when in a selected state.

You can disable toggle buttons if required by context or user permissions using the disabled prop. Disabling a toggle button will prevent the user from interacting with it and suppresses all functionality.

A ToggleButtonGroup allows users to make a mutually exclusive selection from a set of related commands—with only one option selected at a time.

• Number of options: A toggle button group should always contain two or more options related by function or context. Examples include text alignment (left, center, right, justified) or risk level (high, medium, low).
• Text and icon: Use text description in addition to or instead of an icon if the options in the toggle button group are high priority. Users will be less likely to overlook the options.

By default, a toggle button group has horizontal alignment. To present the options in a stacked layout, orientate the group vertically using the orientation=”vertical” prop.

When oriented vertically, the group will resize to fit the longest toggle button, with all other buttons in the group extending to fill the same width.

Setting the toggle button group as read-only using the readOnly prop will render the toggle button group in a non-interactive state and with read-only styles. This is useful for scenarios where users need to view the current selection, but may not have the right permissions to change it.

If a toggle button is in a selected state within a read-only toggle button group, it will retain its visual style to indicate selection and remain focusable via keyboard navigation, ensuring that users can perceive the selection through assistive technologies.

Disabling a toggle button group using the disabled prop will suppress functionality for all buttons within it.

• Disable or Read-Only: Disable the group when it is not relevant or permitted in the current user flow; in this state, it will not be focusable for screen readers. Set the group to read-only when it is important for the user to know which option is currently selected. When set to read-only, the selected button will still be focusable for screen readers but will be indicated as non-interactive.

Sentiment can be set on a toggle button group or individual buttons within a group. Setting sentiment on individual buttons allows for a mixed group.

Set sentiment by using the sentiment prop, either on the group as a whole or on individual toggle buttons within the group.

The appearance prop allows you to define the selected appearance for all buttons in the toggle button group as either solid or bordered.

• Set Appearance on the Group: Although it is possible to mix sentiment within a group, it is not recommended to do the same with appearance as it can lead to visual inconsistency and diminish clarity for the user.

The standalone ToggleButton enables users to seamlessly switch between two distinct states, such as on/off or active/inactive.

Include both icons and text within toggle buttons to visually reinforce the intent of the options or when additional context can aid decision-making, such as selecting a document type or a text style.

• To reduce visual noise and mitigate alignment issues, use icons in toggle button labels consistently across all options in a toggle button group.
• Icons should only be placed to the left of the text in order to further describe the action, placing to the right would suggest an onward direction or movement.

You can use toggle buttons with icons only. Use an icon-only button when screen space is limited, and the icon is easily understandable.

• Self-explanatory icons: An icon-only toggle button should be intuitive, ideally using well-known recognisable symbols. If the purpose of the button isn’t clear from the icon alone, add a label.
• Icon switching: Consider switching icons based on the selection state of the toggle button, for instance by switching between outline and solid icon variants or active/inactive icons, such as locked and unlocked.
• Accessibility: Provide an accessible label for each toggle button.
• Tooltips: Use Tooltip to provide additional context for each toggle button.

You can configure toggle buttons to only display text if you can’t identify a suitable or intuitive icon.

• Label switching: Consider changing the text on the toggle button to complement its selected state. If the label does change based on the selected state, ensure any changes to the button's width do not adversely affect alignment.

In addition to neutral, toggle button has four other sentiments available — accented, positive, caution and negative. You can set this using the sentiment prop. Sentiments are based on the following recommendations:

• Accented: Allows greater visual emphasis to be placed on actions.
• Positive: Indicates actions that result in positive outcomes.
• Caution: Alerts users to potential consequences that may arise from taking an action.
• Negative: Indicates actions that lead to negative outcomes.

There are two different appearances that can be applied to the selected state of a toggle button: solid and bordered. By default, toggle buttons are set to solid. You can change the appearance to bordered using the appearance prop.

• Visual hierarchy: Changing the appearance to bordered can reduce the prominence of the toggle button when in a selected state.

You can disable toggle buttons if required by context or user permissions using the disabled prop. Disabling a toggle button will prevent the user from interacting with it and suppresses all functionality.

A ToggleButtonGroup allows users to make a mutually exclusive selection from a set of related commands—with only one option selected at a time.

• Number of options: A toggle button group should always contain two or more options related by function or context. Examples include text alignment (left, center, right, justified) or risk level (high, medium, low).
• Text and icon: Use text description in addition to or instead of an icon if the options in the toggle button group are high priority. Users will be less likely to overlook the options.

By default, a toggle button group has horizontal alignment. To present the options in a stacked layout, orientate the group vertically using the orientation=”vertical” prop.

When oriented vertically, the group will resize to fit the longest toggle button, with all other buttons in the group extending to fill the same width.

Setting the toggle button group as read-only using the readOnly prop will render the toggle button group in a non-interactive state and with read-only styles. This is useful for scenarios where users need to view the current selection, but may not have the right permissions to change it.

If a toggle button is in a selected state within a read-only toggle button group, it will retain its visual style to indicate selection and remain focusable via keyboard navigation, ensuring that users can perceive the selection through assistive technologies.

Disabling a toggle button group using the disabled prop will suppress functionality for all buttons within it.

• Disable or Read-Only: Disable the group when it is not relevant or permitted in the current user flow; in this state, it will not be focusable for screen readers. Set the group to read-only when it is important for the user to know which option is currently selected. When set to read-only, the selected button will still be focusable for screen readers but will be indicated as non-interactive.

Sentiment can be set on a toggle button group or individual buttons within a group. Setting sentiment on individual buttons allows for a mixed group.

Set sentiment by using the sentiment prop, either on the group as a whole or on individual toggle buttons within the group.

The appearance prop allows you to define the selected appearance for all buttons in the toggle button group as either solid or bordered.

• Set Appearance on the Group: Although it is possible to mix sentiment within a group, it is not recommended to do the same with appearance as it can lead to visual inconsistency and diminish clarity for the user.