@asphalt-react/button v1.19.0
Button
Buttons provide a way to trigger an action. The caption of a Button should hint what action it'll perform. The caption is typically text but Buttons can also have an icon with text or just an icon (which we call as Icon Button).
Buttons come in 4 variants to emphasize different levels:
- Primary (default): For strong call to an action.
- Secondary: For supporting primary buttons.
- Tertiary: For actions less important than primary actions.
- Nude: For least important actions.
There are 3 intents, which paired with the above variants address multiple supportive actions:
- Brand (default): For most recommended action.
- Danger: For actions that have some element of risk like deletion.
- System: For less recommended actions.
Variants and an intents are mutually exclusive. Button falls back to the default value if a variant or intent occurs more than once. For example, using primary
and nude
together will fallback to a primary
variant.
Button features the ability to render a semantic link styled as a button (which we call Link Button). Link Buttons and Icon Link Buttons — icon as caption — handle security and privacy risks if the link opens in a new tab.
Button package exports a named ToggleButton component as well. A ToggleButton is a digital switch to turn an option on or off.
Buttons support 4 sizes: - extra small (xs) - small (s) - medium (m) - large (l)
Buttons's caption decides its width by default, but it can also stretch to take its container's width. The rendered button element has a type
attribute set to "button". You may override the type
attribute if needed.
Buttons accept React ref
to give access to the underlying element. They accept most of the button element's attributes such as disabled
& onClick
and supports data-* attributes.
Accessibility
- All buttons are focusable and keyboard navigable; tab (or shift+tab when tabbing backwards).
- space and enter keys trigger the buttons when in focus; toggles the state of ToggleButton.
- ToggleButton has a role of “switch”.
- The on/off state of ToggleButton determines the value of
aria-checked
attribute. - enter key triggers the link buttons when in focus.
- All buttons accept the aria-* attributes button role.
- Link buttons accept the aria-* attributes for the link role.
Accessibility must-haves
- Add
aria-label
oraria-labelledby
in Icon Button & icon-only variant of ToggleButton to help assitive technologies.
Usage
import { Button } from '@asphalt-react/button'
<Button>Click me</Button>
Props
children
React node for button's caption
type | required | default |
---|---|---|
node | true | N/A |
primary
Renders a primary variant
type | required | default |
---|---|---|
bool | false | false |
secondary
Renders a secondary variant
type | required | default |
---|---|---|
bool | false | false |
tertiary
Renders a tertiary variant
type | required | default |
---|---|---|
bool | false | false |
nude
Renders a nude variant
type | required | default |
---|---|---|
bool | false | false |
brand
Renders brand intent
type | required | default |
---|---|---|
bool | false | false |
danger
Renders danger intent
type | required | default |
---|---|---|
bool | false | false |
system
Renders system intent
type | required | default |
---|---|---|
bool | false | false |
link
Renders a link button
type | required | default |
---|---|---|
bool | false | false |
as
Link element to render. Accepts an HTML element or a React component.
type | required | default |
---|---|---|
elementType | false | "a" |
asProps
Accepts props & attributes for the link element.
type | required | default |
---|---|---|
object | false | { href: "." } |
icon
Renders an icon button
type | required | default |
---|---|---|
bool | false | false |
compact
Renders an icon button with less padding. Works only with a nude
icon button. Does not support any intent.
type | required | default |
---|---|---|
bool | false | false |
qualifier
Qualifiers are icons that enhance the caption. Button 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 button, useicon
prop instead
type | required | default |
---|---|---|
element | false | null |
qualifierEnd
Appends qualifier to the caption
type | required | default |
---|---|---|
bool | false | false |
size
Controls size of button. Possible values are "xs", "s", "m", "l" for extra small, small, medium & large respectively
type | required | default |
---|---|---|
enum | false | "m" |
stretch
Stretches Button to take it's container width
type | required | default |
---|---|---|
bool | false | false |
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 — should produce an immediate result. The caption should always reflect the current logical state of the button.
There are two variants:
- text-only
- icon-only
ToggleButton vs Checkbox
Similar to ToggleSwitches, 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.
Usage
import { ToggleButton } from '@asphalt-react/button'
<ToggleButton text="mute" on />
Props
text
Label for text-only variant
type | required | default |
---|---|---|
string | false | N/A |
icon
Icon for icon-only variant. Accepts SVG or SVG wrapped React component
Note: icon
prop overrides text
prop
type | required | default |
---|---|---|
node | false | N/A |
children
React node for caption
Note: Both icon
and text
props override children
type | required | default |
---|---|---|
node | false | N/A |
on
Sets the state of button
type | required | default |
---|---|---|
bool | false | false |
size
Sets the size of button. Possible values are "s", "m", "l"
for small, medium & large respectively
type | required | default |
---|---|---|
enum | false | "m" |
5 months ago
7 months ago
9 months ago
9 months ago
12 months ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
2 years ago
2 years ago
1 year ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago