Button
Buttons provides a way to trigger an action. The caption of a Button should hint what action will occur. Buttons come in 3 sizes: small, medium and large. Along with the main component, Button provides 4 named exports:
Buttons can render an icon or text before or after the caption.
Buttons except ToggleButtons:
-
can stretch to take their parent's width.
-
can take React
ref
. -
have 4 variants:
- Primary: For strong call to an action.
- Secondary: For supporting primary buttons.
- Outline: For actions less important than primary.
- Nude: For least important actions.
-
IconButton & IconButtonLink don't have Secondary and Outline variants
💡 Don't use
outline
buttons as an alternative tosecondary
buttons. Onlysecondary
buttons should be used withprimary
buttons.
All buttons accept most button attributes.
Accessibility considerations
- All buttons are focusable and support keyboard navigation; tab (or shift+tab when tabbing backwards)
- space and enter keyboard shortcuts trigger the buttons when in focus; toggles the state of ToggleButton.
- ToggleButton has a role of “switch”.
- The state of ToggleButton determines the value of
aria-checked
attribute. - Add
aria-label
oraria-labelledby
in IconButton & icon-only variant of ToggleButton to help assitive technologies. - enter keyboard shortcut triggers the link buttons when in focus.
- All buttons accept the button aria-* attributes.
- Both link buttons accept the link aria-* attributes.
Props
children
React node for button's caption
type | required | default |
---|---|---|
node | true | N/A |
size
Controls size of button. Possible values are "s", "m", "l" for small, medium & large respectively
type | required | default |
---|---|---|
enum | false | "m" |
stretch
Button matches width of it's container
type | required | default |
---|---|---|
bool | false | false |
nude
Renders a nude button
type | required | default |
---|---|---|
bool | false | false |
primary
Applies primary brand color
type | required | default |
---|---|---|
bool | false | N/A |
secondary
Renders a secondary button
type | required | default |
---|---|---|
bool | false | N/A |
outline
Renders an outline button
type | required | default |
---|---|---|
bool | false | N/A |
danger
Renders as danger button
type | required | default |
---|---|---|
bool | false | N/A |
qualifier
Qualifiers provide a hint about the action a button will perform. Appends (default) or prepends an icon to the button's caption. Accepts SVG or string.
Checkout @asphalt-react/iconpack
for SVG wrapped React components.
type | required | default |
---|---|---|
union | false | null |
qualifierStart
Renders qualifier before the button's caption
type | required | default |
---|---|---|
bool | false | true |
qualifierEnd
Renders qualifier after the button's caption. Has priority over qualifierStart
.
type | required | default |
---|---|---|
bool | false | false |
iconInheritsColor
Icons inherits Button’s color
property. Use it to override the icon’s default color with the Button’s caption color.
type | required | default |
---|---|---|
bool | false | false |
IconButton
IconButton provides a way to render an icon as a button.
Props
icon
Renders an icon for the caption. Accepts an inline SVG or SVG wrapped React component
type | required | default |
---|---|---|
element | true | N/A |
primary
Applies primary brand color
type | required | default |
---|---|---|
bool | false | N/A |
danger
Renders as danger button
type | required | default |
---|---|---|
bool | false | N/A |
nude
Renders a nude icon button
type | required | default |
---|---|---|
bool | false | false |
size
Determines the size. Possible values are "s", "m", "l" for small, medium & large respectively/
type | required | default |
---|---|---|
enum | false | "m" |
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.
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" |
ButtonLink
ButtonLink is a semantic link element styled as a Button component.
It supports two variants - Primary & Secondary. It can also render an icon (qualifier) along with the caption. There are three sizes available - small, medium & large.
ButtonLink detects target="_blank"
in the props and adds an icon hinting users that the link will open in a new tab (or window). However, you can provide your custom icon via qualifier
prop to override this default behavior.
Security and privacy risks
When a link opens in a new tab, users' security and privacy may be at risk. To prevent this both ButtonLink and IconButtonLink checks the value of target
attribute and adds rel="noreferrer"
(why not rel="noopener noreferrer"
) if the value is other than _self, _top or _parent. To override this default behavior, you can pass a rel
attribute in tagProps
prop.
Props
children
React node for the caption.
type | required | default |
---|---|---|
node | true | N/A |
tagProps
Accepts props & attributes for the link element.
type | required | default |
---|---|---|
object | true | N/A |
as
Link element to render. Accepts an HTML element or a React component.
type | required | default |
---|---|---|
elementType | false | "a" |
size
Size of ButtonLink. Possible values are "s", "m", "l" for small, medium & large respectively.
type | required | default |
---|---|---|
enum | false | "m" |
primary
Applies primary brand styles.
type | required | default |
---|---|---|
bool | false | N/A |
secondary
Applies secondary styles.
type | required | default |
---|---|---|
bool | false | N/A |
qualifier
Qualifiers provide a hint about the action a ButtonLink will perform. Appends or prepends (default) an icon to the caption. Accepts SVG or string.
Checkout @asphalt-react/iconpack
for SVG wrapped React components.
type | required | default |
---|---|---|
union | false | null |
qualifierEnd
Appends qualifier to the caption.
type | required | default |
---|---|---|
bool | false | false |
IconButtonLink
IconButtonLinks are semantic links styled as an IconButton component. Supports two variants - Primary & Nude. There are three sizes available - small, medium & large.
Props
icon
Renders an icon for the caption. Accepts an inline SVG or SVG wrapped React component
Checkout @asphalt-react/iconpack
for SVG wrapped React components.
type | required | default |
---|---|---|
element | true | N/A |
tagProps
Accepts props & attributes for the link element
type | required | default |
---|---|---|
object | true | N/A |
as
Link element to render. Accepts an HTML element or a React component.
type | required | default |
---|---|---|
elementType | false | "a" |
primary
Applies primary brand styles.
type | required | default |
---|---|---|
bool | false | N/A |
nude
Applies nude styles
type | required | default |
---|---|---|
bool | false | N/A |
size
Size of IconButtonLink. Possible values are "s", "m", "l" for small, medium & large respectively
type | required | default |
---|---|---|
enum | false | "m" |