Skip to main content

Action toggle

Action toggle is a special use button that allows users to switch between two related states. It is often used for activate/deactivate functions and can be grouped together for related functions. Their intended use is for interacting with a particular element or region on the page. Examples are switching between “Play” and "Pause," “Start” and “Stop,” or “Connect” and “Disconnect.” It keeps the user within a functional context rather than navigating somewhere else. Use one or more as part of an interactive in-page user experience.

Example

An action toggle button with a glyph

Best practices

The action toggle is usually found as a UI control on or around an interactive region of the page that affects the region or items within the region. It usually represents a switch between one of two states.

Do

  • Use an action toggle for specific control around a functional state.
  • Labelling can be done using a glyph and text, but could also contain just a glyph or just text. In all cases, the labelling must be clear as to function. If not, consider expanding the labelling.
  • When only a glyph is used to label the button, include a tooltip in a span element following the button element.
  • Multiple related action toggle controls should be grouped together visually to reinforce their associated functionality.
  • Co-locate the action toggle within the interactive region of the page it is associated with.

Don’t

  • Do not use an action toggle to navigate to another page or experience. Use a hyperlink or call to action instead.
  • Do not place an action toggle so it is hidden or obscured in the clutter of the page.
  • Do not use an action toggle to switch between more than two states.

Related

Button
Hyperlink
Call to action

Accessibility

  • Set the aria-label attribute to a brief text description of the button’s function when using only a Glyph for the button label or when an expanded description is helpful for those using screen readers.
  • It is not necessary to set the attribute role="button" in the button element.
  • A glyph-only action trigger should enhance accessibility for sighted users by using the tooltip component with the action trigger. Make sure to associate the tooltip using the data-js-describedby attribute to prevent redundent content for screen readers.

Options

The only options available for action toggle are applied using attributes and CSS classes.

  • Classes: The following classes are required.

    • c-action-toggle: To make a button element into an action toggle, assign it the class c-action-toggle.
    • c-tooltip: Set the span element’s class to c-tooltip.
  • Text/glyph: There are three labeling combinations available: text and glyph, text only, or glyph only.

    • Text: To use text, just add a string as normal for the button element. This is the text for the initial toggle state. If no text is included, no text label appears on the button.
    • Glyph: To use a glyph label on the button, add the class c-glyph and the class name of the initial glyph to the button element.
    • Predefined Glyphs: The following glyph classes are predefined:
      • glyph-edit
      • glyph-cancel
      • glyph-global-nav-button
      • glyph-shopping-cart
      • glyph-chevron-left
      • glyph-chevron-right
      • glyph-chevron-up
      • glyph-chevron-down
      • glyph-play
      • glyph-info
      • glyph-download
  • Tooltip: To add a tooltip to the action toggle, add a span element immediately after the button element. The span surrounds the tooltip text. Use the following configuration:

    • Add the attribute data-f-describedby to the button element and assign it the value of the span's unique id.
    • Assign the span element the class c-tooltip.
    • Assign the span element the role of "tooltip."
    • Set the span element's aria-hidden attribute to the value "true."
  • Toggle labels: To set the labels for the toggled state, you must set two attributes in the button element:

    • Set the data-toggle-label attribute to a text string that briefly describes the button's initial functional state.
    • Set the data-toggle-glyph attribute to the name of the glyph used with the button to indicate its initial functional state.
  • Toggled: Add the class f-toggle to the button element when you need to initialize the action-toggle in a toggled state. This is the equivalent of presetting the toggle state. Note that the glyph class name used should reflect the toggled state, not the normal state.

  • Align margin: Add a class of f-align-margin when you need to align the action toggle with a content block above it or below it.

  • data-f-described-by: Set the value of this microdata attribute equal to the id of the tooltip span element associated with the button.

  • Disabled: To disabled the control, set the Boolean attribute disabled in the button element to the value “disabled.”

  • Role: Set the role attribute in the span element to “tooltip.” No role attribute is required for the button element.

Development

  • Schema definition: The action-toggle schema defines the acceptable configurations, requirements, and options for each component.

Code and preview

Glyph only

<button class="c-action-toggle c-glyph glyph-play f-toggle" data-toggled-label="Pause" data-toggled-glyph="glyph-pause" aria-label="Play" data-f-describedby="glyphOnlyPause"></button>
<span id="glyphOnlyPause" class="c-tooltip" role="tooltip" aria-hidden="true">Pause</span>

Glyph only - initialized without toggle

<button class="c-action-toggle c-glyph glyph-play" data-toggled-label="Pause" data-toggled-glyph="glyph-pause" aria-label="Play" data-f-describedby="glyphOnlyPlay"></button>
<span id="glyphOnlyPlay" class="c-tooltip" role="tooltip" aria-hidden="true">Pause</span>

Text with glyph

<button class="c-action-toggle c-glyph glyph-play f-toggle" data-toggled-label="Pause" data-toggled-glyph="glyph-pause">Play</button>

Text with glyph - initialized without toggle

<button class="c-action-toggle c-glyph glyph-play" data-toggled-label="Pause" data-toggled-glyph="glyph-pause">Play</button>

Text only

<button class="c-action-toggle f-toggle" data-toggled-label="Pause">Play</button>

Text only - initialized without toggle

<button class="c-action-toggle" data-toggled-label="Pause">Play</button>

All Glyphs

<div class="c-group f-wrap-items">
    <button class="c-action-toggle c-glyph glyph-play" data-toggled-label="Pause" data-toggled-glyph="glyph-pause">Play</button>
    <button class="c-action-toggle c-glyph glyph-play f-toggle" data-toggled-label="Pause" data-toggled-glyph="glyph-pause">Play</button>
    <button class="c-action-toggle c-glyph glyph-chevron-right f-toggle" data-toggled-label="Previous" data-toggled-glyph="glyph-chevron-left">Next</button>
    <button class="c-action-toggle c-glyph glyph-chevron-up f-toggle" data-toggled-label="Down" data-toggled-glyph="glyph-chevron-down">Up</button>
</div>

Text with glyph and align margin option

<button class="c-action-toggle c-glyph glyph-play f-align-margin f-toggle" data-toggled-label="Pause" data-toggled-glyph="glyph-pause">Play</button>

Text with glyph and align margin option - initialized without toggle

<button class="c-action-toggle c-glyph glyph-play f-align-margin" data-toggled-label="Pause" data-toggled-glyph="glyph-pause">Play</button>