@asphalt-react/toggle-button v2.0.0-alpha.8

ToggleButton

A ToggleButton is a digital switch to turn an option on or off. Switching between the states — as a result of direct user action or a programmatic event. The caption should always reflect the current logical state of the button.

ToggleButton comes in 3 variants -

• Text only: ToggleButton having text caption.
• Icon only: Icon as caption (which we also refer as Icon ToggleButton). For space constraint uses, Icon ToggleButton also has a compact form. The compact form also supports an option to put more emphasis on the icon instead of the button.
• Text with icon: Text with icon (left or right to the text) as caption.

ToggleButton supports 4 sizes: - extra small (xs) - small (s) - medium (m) - large (l)

ToggleButtons accept most of the button element's attributes such as disabled & onClick and supports data-* attributes.

ToggleButton vs Checkbox

ToggleButtons are not an alternative to Checkboxes. They are not form controls and should not appear inside a form. ToggleButtons should only manipulate local UI states, i.e. they should not directly or indirectly initiate a remote API call to change database states.

ToggleButton vs ToggleSwitch

Both of them provide options to toggle between states. Consider the following points to choose between them:

1. Prefer ToggleSwitches to toggle states on mobile; they support swipe gestures
2. ToggleButtons fit better in designs with space constraints
3. Use ToggleButtons to programmatically toggle the state. For example, you can bind a keyboard shortcut to a mute button in a video player.

Accessibility

1. ToggleButton is focusable and keyboard navigable; tab (or shift+tab when tabbing backwards).
2. space and enter toggles the state of ToggleButton.
3. ToggleButton has a role of “button”.
4. ToggleButton uses aria-pressed to assist screen readers; the on/off state of ToggleButton determines its value.
5. ToggleButton accept the aria-* attributes button role.

Accessibility must-haves

1. Add aria-label or aria-labelledby in Icon ToggleButton to help assitive technologies.

Usage

import { ToggleButton } from '@asphalt-react/toggle-button'

<ToggleButton on>mute</ToggleButton>

Props

children

React node for caption

on

Sets the state of button

size

Sets the size of button. Possible values are "xs", "s", "m", "l" for extra small, small, medium & large respectively

icon

Renders an Icon ToggleButton.

compact

Renders an Icon ToggleButton with less spacing around icons.

emphasize

Emphasizes the icon instead of background by coloring it. Works only for Compact Icon ToggleButton

qualifier

Qualifiers are icons that enhance the caption. ToggleButton prepends the qualifier by default

Accepts SVG or SVG wrapped React component. Checkout @asphalt-react/iconpack for SVG wrapped React components.

⚠️ Do not use qualifier to render an Icon ToggleButton, use icon prop instead

qualifierEnd

Appends qualifier to the caption