@asphalt-react/toggle-button v2.5.0

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.

ToggleButtons can form a group by sticking to each other which enables creating composite components using ToggleButtons.

Usage

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

<ToggleButton on>mute</ToggleButton>

Variants

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.

Sizes

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

Group ToggleButtons

You can group two or more toggle buttons by sticking them together using stickStart, stickEnd & stick props.

Set stickEnd to true on start button and stickStart to true on the end button. If you are grouping more that two buttons use stickEnd & stickStart both on all the buttons in the middle.

Use stick prop optionally on the end button to enhance it's style in order to make default and second button look good together. stick renders the toggle button without left border.

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

<div>
    <ToggleButton on stickEnd>left align</ToggleButton>
    <ToggleButton stickStart stick>right align</ToggleButton>
<div>

When to use a ToggleButton?

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. ToggleButtons accept most of the button element's attributes such as disabled & onClick and supports data-* attributes.

2. ToggleButton is focusable and keyboard navigable; tab (or shift+tab when tabbing backwards).

3. space and enter toggles the state of ToggleButton.

4. ToggleButton has a role of “button”.

5. ToggleButton uses aria-pressed to assist screen readers; the on/off state of ToggleButton determines its value.

6. ToggleButton accept the aria-* attributes button role.

Accessibility must-haves

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

Props

children

React node for caption

seamless

Renders a seamless variant

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

link

Renders a link ToggleButton

as

Link element to render. Accepts an HTML element or a React component.

asProps

Accepts props & attributes for the link element.

icon

Renders an Icon ToggleButton.

compact

Renders a ToggleButton with less spacing around.

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

stickStart

Adapts to let other buttons stick to its start

stickEnd

Adapts to let other buttons stick to its end

stick

Enhances the style of the supporting button.

underline

Adds underline in link ToggleButton