@asphalt-react/button

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.

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.
• 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 or aria-labelledby in Icon Button 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, use icon 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