@asphalt-react/button

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:

• IconButton
• ToggleButton
• ButtonLink
• IconButtonLink

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 to secondary buttons. Only secondary buttons should be used with primary 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 or aria-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

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"