@asphalt-react/button/README.md

Button

# Button

![npm](https://img.shields.io/npm/dt/@asphalt-react/button?style=flat-square)
[![npm version](https://badge.fury.io/js/@asphalt-react%2Fbutton.svg)](https://badge.fury.io/js/@asphalt-react%2Fbutton)

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's caption decides its width by default, but it can also stretch to take its container's width. Buttons can form a group by sticking to each other enabling use cases like split button.

## Usage

```jsx
import { Button } from '@asphalt-react/button'

<Button>Click me</Button>
```

## Variants & Intents

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.

## Sizes

Buttons support 4 sizes:
\- extra small (xs)
\- small (s)
\- medium (m)
\- large (l)

## Link styled as Button

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.

## Split Button

You can make a [split button](https://www.nngroup.com/articles/split-buttons/) by grouping a default action button with a menu button.

Set `stickEnd` to `true` on start button and `stickStart` to `true` on the end button.

Use `stick` prop optionally on the the end button to enhance it's style in order to make default and menu button look good together. `stick` adds spacing to the left of the `primary`, `tertiary` & `nude` variant buttons, in case of `secondary` variant it removes the left border.

```jsx
import { Button } from '@asphalt-react/button'

<div>
    <Button stickEnd>Default action</Button>
    <Button stickStart stick>Menu</Button>
</div>
```

## Accessibility

1. Buttons accept React [`ref`](https://reactjs.org/docs/refs-and-the-dom.html) to give access to the underlying element.

2. They accept most of the [button element's attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button) such as `disabled` & `onClick` and supports [data-\* attributes](https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Use_data_attributes).

3. The rendered button element has a `type` attribute set to "button". You may override the `type` attribute if needed.

4. All buttons are focusable and keyboard navigable; <kbd>tab</kbd> (or <kbd>shift</kbd>+<kbd>tab</kbd> when tabbing backwards).

5. <kbd>space</kbd> and <kbd>enter</kbd> keys trigger the buttons when in focus.

6. <kbd>enter</kbd> key triggers the link buttons when in focus.

7. All buttons accept the aria-\* attributes [button role](https://www.w3.org/TR/wai-aria-1.1/#button).

8. Link buttons accept the aria-\* attributes for the [link role](https://www.w3.org/TR/wai-aria-1.1/#link).

## Accessibility must-haves

Add `aria-label` or `aria-labelledby` in Icon Button to help assistive technologies.

[comment]: # "Button Props"

## 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

Shrinks the size of the Button keeping the size of the contents intact. Useful for use-cases with space-constraints.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### qualifier

Qualifier is an icon or a word that enhances the caption. Button prepends the qualifier by default. Accepts SVG for icons. 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 |
| ----- | -------- | ------- |
| union | 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   |

### stickStart

Adapts to let other buttons stick to its start

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### stickEnd

Adapts to let other buttons stick to its end

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### stick

Enhances the style of the supporting button.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### underline

Adds underline in link Button

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | true    |