import { Meta, Story, Source } from "@storybook/addon-docs";

<Meta title="Documentation/Button" />

# Button

Use buttons for actions in forms, dialogs, and more with support for style, block, icon, and state.

For pairings in the bottom left corner of a page or component, the `primary` call to action will go on the left side of a button group with the `secondary` call to action option on the left.

Pairings in the top right corner of a page, should have the `primary` call to action on the right.

Groups of buttons should have 1rem of spacing between them.

## Choosing the `<a>` or `<button>`

Buttons can use either the `<a>` or `<button>` tags. Choose which based on the action the button takes:

- If navigating to a new page, use `<a>`
- If taking an action on the current page use `<button>`
- If the button launches a dialog, use `<button>`

## Submit and async actions

Both submit and async action buttons use a loading button state while an action is taken.

<Story id="component-library-button--loading" />

If your button is preforming a long running task in the background like a server API call, be sure to review the [Async Actions Directive](https://components.bitwarden.com/?path=/story/component-library-async-actions-overview--page).

## Styles

There are 3 main styles for the button: Primary, Secondary, and Danger.

### Primary

<Story id="component-library-button--primary" />

Use the primary button styling for all Primary call to actions. An action is "primary" if it relates to the main purpose of a page. There should never be 2 primary styled buttons next to each other.

### Secondary

<Story id="component-library-button--secondary" />

The secondary styling should be used for secondary calls to action. An action is "secondary" if it relates indirectly to the purpose of a page. There may be multiple secondary buttons next to each other; however, generally there should only be 1 or 2 calls to action per page.

### Danger

<Story id="component-library-button--danger" />

Use the danger styling only in settings when the user may preform a permanent action.

## Disabled UI

Both the disabled and loading states use the default state’s color with a 60% opacity or `tw-opacity-60`.

<Story id="component-library-button--disabled" />

## Block

Typically button widths expand with thier text. In some causes though buttons may need to be block where the width is fixed and the text wraps to 2 lines if exceeding the button’s width.

<Story id="component-library-button--block" />

## Accessibility

### Color contrast

All button styles are WCAG compliant when displayed on `background` and `background-alt` colors. To use a button on a different background, double check that the color contrast is sufficient in both the light and dark themes.

### Loading Buttons

Include an `aria-label` attribute that defaults to “loading” but can be configurable per implementation. On click, the screen reader should announce the `aria-label`. Once the action is compelted, use another messaging pattern to alert the user that the action is complete (example: success toast).
