Toggle button usage guidelines

Usage guidelines API

A toggle button allows users to switch between two distinct states (on/off, active/inactive). It functions similarly to a checkbox or radio button, but offers a more immediate visual feedback for the selected state.

When to use

For configuration where users can toggle a feature on or off or select from a list (example: “Shape: Square/Standard”; “Backsides: Color, Blank, Gray”).
For rich text editors or similar tools to apply or remove formatting styles (example: “Bold”, “Italic”, “Underline”).
To quickly apply or remove a single filter (example: “Show favorites”).

When not to use

For initiating an action that doesn’t involve a toggle state. Use a button for submitting forms, navigating, or performing one-time actions.
When more than two states are required within a single control. Consider using a radio group or a select for multiple exclusive options.
When the content is generated by the user.

Properties

import { Stack, ToggleButton } from '@cimpress-ui/react';

export default function Demo() {
  return (
    <Stack gap={16} direction="horizontal" wrap>
      <ToggleButton isSelected>Selected</ToggleButton>
      <ToggleButton>Unselected</ToggleButton>
      <ToggleButton isDisabled>Disabled</ToggleButton>
    </Stack>
  );
}

State	Use cases
Selected	The selected state indicates that an option is selected or “turned on”. The user is saying yes, they want this option.
Unselected	The unselected state indicates that an option is unselected or “turned off”. The user is saying no, they don’t want this option.
Disabled	Disabled toggle buttons cannot be interacted with, focused, nor accessed in any manner by assistive technologies. The disabled state should only be used for irrelevant options that cannot be selected.

Size

Preview
Code

import { Stack, ToggleButton } from '@cimpress-ui/react';

export default function Demo() {
  return (
    <Stack direction="horizontal" gap={16} align="center" wrap>
      <ToggleButton size="small">Small</ToggleButton>
      <ToggleButton size="medium">Medium</ToggleButton>
      <ToggleButton size="large">Large</ToggleButton>
    </Stack>
  );
}

Value	Use cases
Small	Used sparingly for more compact UI areas where space is severely limited.
Medium (default)	The default and most common size. Use this for regular controls, and when placed next to other form components like select and text fields to maintain consistent height.
Large	Use sparingly, primarily to achieve visual consistency with other large elements, not for emphasis.

Icon-only toggle button

Preview
Code

import { ToggleIconButton } from '@cimpress-ui/react';
import { IconTextBold } from '@cimpress-ui/react/icons';

export default function Demo() {
  return <ToggleIconButton icon={<IconTextBold />} aria-label="Bold" />;
}

Use extremely sparingly. Icons can be confusing when used for unusual actions or inconsistently, so icon-only toggle buttons should only be used for very common options like “Bold”, “Italic”, and “Underline”.

Toggle button group

Preview
Code

Text alignment

import { ToggleButton, ToggleButtonGroup } from '@cimpress-ui/react';

export default function Demo() {
  return (
    <ToggleButtonGroup label="Text alignment">
      <ToggleButton value="left">Left</ToggleButton>
      <ToggleButton value="center">Center</ToggleButton>
      <ToggleButton value="right">Right</ToggleButton>
    </ToggleButtonGroup>
  );
}

When multiple toggle buttons are logically related or mutually exclusive, they should be contained within a toggle button group. This group can be accompanied by a title, a description, and it can display an error state. Groups allow single or multiple selection.

Formatting and layout

Placement

Toggle buttons should be placed logically within the UI, near the content or settings that they control. For text formatting, they typically reside in toolbars. For configuration, they might be in settings panels or alongside relevant content.

Toggle button consistency

Maintain visual consistency by using toggle buttons of the same size and styling within a group. Mixing toggle buttons with and without icons can create visual imbalance.

Don't

Text alignment

Spacing

Toggle buttons should have 8px of spacing between them.

Form alignment

Toggle button groups used in forms should always include a title to give users context. The toggle button group should be left-aligned with the rest of the form elements.

Name

Content writing

Do use clear and concise labels.
Avoid using verbs or actions for the toggle buttons, as they represent a state and not an action.
When toggle buttons are in a group, do include a title for the group if it will give users context for what the options mean.
The toggle button label must remain the same regardless of the selection state.
Use icons that are widely recognizable and clearly convey the action or state.
Consider adding tooltips to clarify the function of icon-only toggle buttons, especially for less common icons. The tooltip text should clearly indicate the toggle button’s purpose.
End the description and error text with a period or equivalent punctuation mark. This helps screen reader users understand where the description and error text ends, and it improves readability for all users.

Behaviors

Flexible width

The width of a toggle button changes dynamically based on the width of its label. The toggle button width is determined by the component and should not be changed.

Text wrapping

Toggle button labels should never wrap. If you find that your label is too long, consider changing the phrasing to shorten the label, or add additional context in the UI outside of the toggle button.

Description text and error text

Toggle button groups can optionally include description text and error text to give users more context and understanding. The description text and error text will always be at the bottom of the group, not underneath any individual toggle button. All text should be limited to one sentence and clearly give users any additional information needed in plain language. Error text must always give users a path to resolving the issue.