Toggle button

ToggleButton allows users to switch between two states, typically representing an on/off or active/inactive status. The corresponding action takes effect immediately. With ToggleButtonGroup, users can make a mutually exclusive selection from a set of related commands—with only one option selected at a time.

Also known as: Button group, Toggle button group, Toggle group, Segmented control

View source code

Note: This tab list includes overflow; tab positions may be inaccurate or change when a tab is selected

Best practices

When a toggle button has both an icon and text, use aria-hidden on the icon so that screen readers don't announce its text.
When a toggle button has an icon only and no text, pass an aria-label to the button that describes its purpose.

On focus

On focus, the screen reader should:

Identify the toggle button.
Read out the text.
Expresses the state.
Read the position of the option within the total number of buttons available.

Keyboard interactions

Key	Function
`Tab`	Tab moves focus into the toggle button group. Focus is set to the active button. If focus is inside the toggle button group, Tab moves focus out of the toggle button group. Focus is set to the next component in the tab order.
`Space` / `Enter`	When focus is on the toggle button and the button is inactive, this action activates the button. If focus is on an active button, this actions keeps the button active.
`Shift` + `Tab`	If focus is inside the toggle button group, this action moves focus out of the component. Focus is set to the previous component in the tab order. If focus is below the toggle button group, this action move focus into the toggle button group. Focus is set to the active button.
`Right arrow` / `Down arrow`	This action moves focus to the next toggle button in the toggle button group. If focus is on the last toggle button, this action wraps focus to the first toggle button.
`Left arrow` / `Up arrow`	This action moves focus to the previous toggle button in the toggle button group. If focus is on the first toggle button, this action wraps focus to the last toggle button.

Best practices

When a toggle button has both an icon and text, use aria-hidden on the icon so that screen readers don't announce its text.
When a toggle button has an icon only and no text, pass an aria-label to the button that describes its purpose.

On focus

On focus, the screen reader should:

Identify the toggle button.
Read out the text.
Expresses the state.
Read the position of the option within the total number of buttons available.

Keyboard interactions

Key	Function
`Tab`	Tab moves focus into the toggle button group. Focus is set to the active button. If focus is inside the toggle button group, Tab moves focus out of the toggle button group. Focus is set to the next component in the tab order.
`Space` / `Enter`	When focus is on the toggle button and the button is inactive, this action activates the button. If focus is on an active button, this actions keeps the button active.
`Shift` + `Tab`	If focus is inside the toggle button group, this action moves focus out of the component. Focus is set to the previous component in the tab order. If focus is below the toggle button group, this action move focus into the toggle button group. Focus is set to the active button.
`Right arrow` / `Down arrow`	This action moves focus to the next toggle button in the toggle button group. If focus is on the last toggle button, this action wraps focus to the first toggle button.
`Left arrow` / `Up arrow`	This action moves focus to the previous toggle button in the toggle button group. If focus is on the first toggle button, this action wraps focus to the last toggle button.

Best practices

When a toggle button has both an icon and text, use aria-hidden on the icon so that screen readers don't announce its text.
When a toggle button has an icon only and no text, pass an aria-label to the button that describes its purpose.

On focus

On focus, the screen reader should:

Identify the toggle button.
Read out the text.
Expresses the state.
Read the position of the option within the total number of buttons available.

Keyboard interactions

Key	Function
`Tab`	Tab moves focus into the toggle button group. Focus is set to the active button. If focus is inside the toggle button group, Tab moves focus out of the toggle button group. Focus is set to the next component in the tab order.
`Space` / `Enter`	When focus is on the toggle button and the button is inactive, this action activates the button. If focus is on an active button, this actions keeps the button active.
`Shift` + `Tab`	If focus is inside the toggle button group, this action moves focus out of the component. Focus is set to the previous component in the tab order. If focus is below the toggle button group, this action move focus into the toggle button group. Focus is set to the active button.
`Right arrow` / `Down arrow`	This action moves focus to the next toggle button in the toggle button group. If focus is on the last toggle button, this action wraps focus to the first toggle button.
`Left arrow` / `Up arrow`	This action moves focus to the previous toggle button in the toggle button group. If focus is on the first toggle button, this action wraps focus to the last toggle button.