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:
- Prefer ToggleSwitches to toggle states on mobile; they support swipe gestures
- ToggleButtons fit better in designs with space constraints
- Use ToggleButtons to programmatically toggle the state. For example, you can bind a keyboard shortcut to a mute button in a video player.
Accessibility
- ToggleButton is focusable and keyboard navigable; tab (or shift+tab when tabbing backwards).
- space and enter toggles the state of ToggleButton.
- ToggleButton has a role of “button”.
- ToggleButton uses
aria-pressed
to assist screen readers; the on/off state of ToggleButton determines its value. - ToggleButton accept the aria-* attributes button role.
Accessibility must-haves
- Add
aria-label
oraria-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
type | required | default |
---|---|---|
node | true | N/A |
on
Sets the state of button
type | required | default |
---|---|---|
bool | false | false |
size
Sets the size of button. Possible values are "xs", "s", "m", "l"
for extra small, small, medium & large respectively
type | required | default |
---|---|---|
enum | false | "m" |
icon
Renders an Icon ToggleButton.
type | required | default |
---|---|---|
bool | false | false |
compact
Renders an Icon ToggleButton with less spacing around icons.
type | required | default |
---|---|---|
bool | false | false |
emphasize
Emphasizes the icon instead of background by coloring it. Works only for Compact Icon ToggleButton
type | required | default |
---|---|---|
bool | false | false |
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 usequalifier
to render an Icon ToggleButton, useicon
prop instead
type | required | default |
---|---|---|
element | false | null |
qualifierEnd
Appends qualifier to the caption
type | required | default |
---|---|---|
bool | false | false |