# Button

The most essential element of a user interface.

---

## Sizes

Our buttons come in four different sizes: Small, Medium, Large & Extra Large. All buttons have a fixed height and padding unless stated differently inside the type

| Size | Usage |
| ---- | ----- |
| `small` | These little buttons are used in compact little spaces, e.g. inside the header of a card. |
| `large` | The large button is mainly used inside an open but content-rich page with multiple actions. This large button also provides a large touchable area for use on touch screens. |
| `xlarge` | When a single page has nothing going on but to promote a single thing with just one button, you should use the extra large button. This button is also great for fast pacing flows with a focus on touch screens. |

## Styles

These are all the styles that are included in all button types (unless stated differently in the types section).

| Style | Usage |
| ----- | ----- |
| `default` | The neutral button is used for all generic actions. |
| `primary` | There should only be one main action on the page. This action should always be a primary styled button. |
| `secondary` | For subsequent actions that encourage our users to fill data like selecting a product. |
| `danger` | For all actions that can be destructive, we use the danger styled button. |

## Types

These are all the styles that are included in all button types (unless stated differently in the types section).

| Type | Usage |
| ---- | ----- |
| **Outline**| Our standard button is for all non-default styles the outline button can transform into a fill button to start encouraging interaction. |
| **Fill**| When taking action is promoted/encouraged we use the fill button. The main CTA should always be a fill. **Not available in default style.** |
| **Icon + Text** | Bringing visual context to what a button will do, can help the user understand and it manages expectations. When space is limited, but actions are required you might want to use an icon only button. |
| **Icon** | A small, often square-shaped button with only an `<Icon>` for CTA. These should be avoided at all costs, unless when dealing with extremely standard usecases. Consider an **Icon + Text** button instead.

---

## Installation

First, make sure you have been through the [Getting Started](https://github.com/lightspeedretail/cirrus#getting-started) steps of adding Cirrus in your application.

If using [Yarn](https://yarnpkg.com/):

```sh
yarn add @lightspeed/cirrus-button
```

Or using [npm](https://www.npmjs.com/):

```sh
npm i -S @lightspeed/cirrus-button
```

---

## Usage

Import required styles in your `.scss`:

```scss
@import '@lightspeed/cirrus-button/Button.scss';
```

### React Component

#### Props

| Prop | Type | Description |
| ---- | ---- | ----------- |
| `children` | React.ReactNode | The content to display inside the button |
| `primary` | boolean | Displays as success button |
| `secondary` | boolean | Displays as secondary button |
| `danger` | boolean | Displays as danger button |
| `fill` | boolean | Displays as fill button |
| `size` | enum['small', 'large', 'xlarge'] | Sets the size of the button |
| `block` | boolean | Displays the button in full width |
| `noSpacing` | boolean | Remove default spacing between button children |
| `disabled` | boolean | Disables the button |
| `loading` | boolean | Displays the loading icon and disables the button |
| `href` | string | Creates a `<a>` link instead of a `<button>` |
| `active` | boolean | Displays the button in an active state |
| `onClick` | function | Callback when button is clicked |
| `onFocus` | function | Callback when button is focused |
| `onBlur` | function | Callback when button is blurred |

#### Example

```jsx
import React from 'react';
import Button from '@lightspeed/cirrus-button';

const MyComponent = () => (
  <div>
    <Button>My Button</Button>
  </div>
);

export default MyComponent;
```

### CSS Component

#### Classes

Besides the base class `.cr-button` you can use one of these classes:

| Type | Class |
| ---- | ----- |
| primary | `.cr-button--primary` |
| secondary | `.cr-button--secondary` |
| danger | `.cr-button--danger` |
| fill | `.cr-button--fill` |
| block | `.cr-button--block` |
| noSpacing | `.cr-button--no-spacing` |
| small | `.cr-button--small` |
| large | `.cr-button--large` |
| xlarge | `.cr-button--xlarge` |
| disabled | `.cr-button--disabled` (only for links, use the `disabled` attribute on `<button>`) |
| loading | `.cr-button--loading` |

The button contains a `<span />` to vertically align the content:

| Type | Class |
| ---- | ----- |
| content | `.cr-button__content` |
| loading | `.cr-button__content--loading` |

#### Example

```html
<button type="button" class="cr-button">
  <span class="cr-button__content">My Button</span>
</button>

<button type="button" class="cr-button cr-button--loading" disabled>
  <span class="cr-button__content cr-button__content--loading">
    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" class="cr-icon cr-icon-spinner cr-spinner" style="width: 1.125rem; height: 1.125rem;">
      <path class="cr-icon__base cr-icon__base-2" d="M8 16A8 8 0 1 1 8 0a8 8 0 0 1 0 16zm0-3A5 5 0 1 0 8 3a5 5 0 0 0 0 10z" opacity=".3"></path>
      <path class="cr-icon__base cr-icon__base-1" d="M8 13a1.5 1.5 0 0 1 0 3A8 8 0 0 1 .323 5.742a1.5 1.5 0 1 1 2.879.846A5 5 0 0 0 8 13z"></path>
    </svg>
  </span>
  <span class="cr-button__content">My Button</span>
</button>
```