npm package: @placardi/button
Description: Placardi UI button component
Author: Alexander Zakharov
Latest version: 0.2.1

# @placardi/button

A button triggers an event or action. It lets users know what will happen next.

## Installation

```bash
npm i @placardi/button
```

## Dependencies

- react
- styled-components
- @placardi/theme

## Usage

### Basic usage

In order to use the button component, wrap the application in global theme provider from `@placardi/theme`. Then, use the button as any regular component.

```tsx
import React, { FC } from 'react';
import ThemeProvider from '@placardi/theme';
import Button from '@placardi/button';

const App: FC = () => (
  <ThemeProvider>
    <Button>Click me!</Button>
  </ThemeProvider>
);

export default App;
```

### Button variant

Buttons can be customised using the `Variant` enum that comes packaged with the button component. Pass a `variant` prop to the button in order to change its appearance. The default is set to `Variant.TEXT`.

```tsx
import React, { FC } from 'react';
import ThemeProvider from '@placardi/theme';
import Button, { Variant } from '@placardi/button';

const App: FC = () => (
  <ThemeProvider>
    <Button variant={Variant.OUTLINED}>Click me!</Button>
  </ThemeProvider>
);

export default App;
```

### Button size

Button size can be customised using the `Size` enum that comes packaged with the button component. Pass a `size` prop to the button in order to change its size. The default is set to `Size.MEDIUM`.

```tsx
import React, { FC } from 'react';
import ThemeProvider from '@placardi/theme';
import Button, { Size } from '@placardi/button';

const App: FC = () => (
  <ThemeProvider>
    <Button size={Size.LARGE}>Click me!</Button>
  </ThemeProvider>
);

export default App;
```

### Button colour

Button colour can be customised using the `Colour` enum that comes packaged with the brand theme. Pass a `colour` prop to the button in order to change its colour. The default is set to `Colour.NEUTRAL`.

```tsx
import React, { FC } from 'react';
import ThemeProvider, { Colour } from '@placardi/theme';
import Button from '@placardi/button';

const App: FC = () => (
  <ThemeProvider>
    <Button colour={Colour.BLUE}>Click me!</Button>
  </ThemeProvider>
);

export default App;
```

### Button children and icons

It is possible to pass children to a button. The most common type would usually be text. It might be necessary to add an icon (either before or after the text) for improved user experience. Icons can be passed using `startIcon` and `endIcon` props.

```tsx
import React, { FC } from 'react';
import ThemeProvider from '@placardi/theme';
import Button from '@placardi/button';
import FavoriteIcon from '@material-ui/icons/Favorite';

const App: FC = () => (
  <ThemeProvider>
    <Button startIcon={<FavouriteIcon />}>Click me!</Button>
    <Button endIcon={<FavouriteIcon />}>Click me!</Button>
  </ThemeProvider>
);

export default App;
```

### Icon button

A button can be turned into an icon button. The recommended way to do so is to pass `Variant.ICON` to `variant` prop and an icon element as a child.

```tsx
import React, { FC } from 'react';
import ThemeProvider from '@placardi/theme';
import Button, { Variant } from '@placardi/button';
import FavoriteIcon from '@material-ui/icons/Favorite';

const App: FC = () => (
  <ThemeProvider>
    <Button variant={Variant.ICON}>
      <FavouriteIcon />
    </Button>
  </ThemeProvider>
);

export default App;
```

### Button on dark background

A button can be used on a dark background. In order to make sure button contents are still visible, it is important to render the light version of the button by passing a `light` prop to `Button` component.

```tsx
import React, { FC } from 'react';
import Button from '@placardi/button';

const App: FC = () => (
  <ThemeProvider>
    <Button light>Click me!</Button>
  </ThemeProvider>
);

export default App;
```