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.
import { ToggleButton } from '@asphalt-react/toggle-button'
<ToggleButton on>mute</ToggleButton>
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)
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>
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.
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.
-
ToggleButtons accept most of the button element's attributes such as
disabled
&onClick
and supports data-* attributes. -
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.
Add aria-label
or aria-labelledby
in Icon ToggleButton to help assistive technologies.
React node for caption
type | required | default |
---|---|---|
node | true | N/A |
Renders a seamless variant
type | required | default |
---|---|---|
bool | false | false |
Sets the state of button
type | required | default |
---|---|---|
bool | false | false |
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" |
Renders a link ToggleButton
type | required | default |
---|---|---|
bool | false | false |
Link element to render. Accepts an HTML element or a React component.
type | required | default |
---|---|---|
elementType | false | "a" |
Accepts props & attributes for the link element.
type | required | default |
---|---|---|
object | false | {} |
Renders an Icon ToggleButton.
type | required | default |
---|---|---|
bool | false | false |
Renders a ToggleButton with less spacing around.
type | required | default |
---|---|---|
bool | false | false |
Emphasizes the icon instead of background by coloring it. Works only for Compact Icon ToggleButton
type | required | default |
---|---|---|
bool | false | false |
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 |
Appends qualifier to the caption
type | required | default |
---|---|---|
bool | false | false |
Adapts to let other buttons stick to its start
type | required | default |
---|---|---|
bool | false | false |
Adapts to let other buttons stick to its end
type | required | default |
---|---|---|
bool | false | false |
Enhances the style of the supporting button.
type | required | default |
---|---|---|
bool | false | false |
Adds underline in link ToggleButton
type | required | default |
---|---|---|
bool | false | true |