npm package: @paprika/button
Description: Button component, for performing an action on the page you’re viewing.
Author: @paprika
Latest version: 1.1.21

<!-- start: Autogenerated - do not modify -->

# @paprika/button

## Description

Button component, for performing an action on the page you’re viewing.

## Installation

```
yarn add @paprika/button
```

or with npm:

```
npm install @paprika/button
```

## Props

### Button

| Prop         | Type                                                                                                                                                                                         | required | default                   | Description                                                                                                      |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| a11yText     | string                                                                                                                                                                                       | false    | null                      | Descriptive a11y text for assistive technologies. By default, text from children node will be used.              |
| canPropagate | bool                                                                                                                                                                                         | false    | true                      | If click events are allowed to propagate up the DOM tree.                                                        |
| children     | node                                                                                                                                                                                         | false    | null                      | Body content of the button.                                                                                      |
| icon         | node                                                                                                                                                                                         | false    | null                      | An icon to be included to the left of children content.                                                          |
| isActive     | bool                                                                                                                                                                                         | false    | null                      | If the button is in an "active" or "selected" state.                                                             |
| isDisabled   | bool                                                                                                                                                                                         | false    | false                     | If the button is disabled.                                                                                       |
| isDropdown   | bool                                                                                                                                                                                         | false    | false                     | If the button includes a down arrow to the right of children content.                                            |
| isFullWidth  | bool                                                                                                                                                                                         | false    | false                     | If the width of the button should span it's parent container (100%).                                             |
| isPending    | bool                                                                                                                                                                                         | false    | false                     | If the button should render in a pending state (with a spinner icon).                                            |
| isSemantic   | bool                                                                                                                                                                                         | false    | true                      | If it will be rendered as a <button> element. If false, a <span> will be rendered via an accessible <RawButton>. |
| isSubmit     | bool                                                                                                                                                                                         | false    | false                     | If the type attribute should "submit", instead of the default "button".                                          |
| kind         | [ Button.types.kind.DEFAULT, Button.types.kind.PRIMARY, Button.types.kind.SECONDARY, Button.types.kind.DESTRUCTIVE, Button.types.kind.FLAT, Button.types.kind.MINOR, Button.types.kind.LINK] | false    | Button.types.kind.DEFAULT | The visual style of the button.                                                                                  |
| onClick      | func                                                                                                                                                                                         | false    | () => {}                  | Callback to be executed when the button is clicked or activated by keyboard. Typically required.                 |
| role         | string                                                                                                                                                                                       | false    | "button"                  | Value for role attribute to override the default of "button".                                                    |
| size         | [ Button.types.size.SMALL, Button.types.size.MEDIUM, Button.types.size.LARGE]                                                                                                                | false    | Button.types.size.MEDIUM  | Size of the button (font size, min-height, padding, etc).                                                        |
| tabIndex     | number                                                                                                                                                                                       | false    | null                      | Value for tabindex attribute to override the default of 0.                                                       |

### Button.Close

| Prop     | Type   | required | default | Description                                                                                         |
| -------- | ------ | -------- | ------- | --------------------------------------------------------------------------------------------------- |
| a11yText | string | false    | null    | Descriptive a11y text for assistive technologies. By default, text from children node will be used. |
| isDark   | bool   | false    | false   | If the close button will be rendered on a dark background and will use inverted colours.            |

### Button.Icon

| Prop     | Type                                                                                                                                                                           | required | default                 | Description                                               |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ----------------------- | --------------------------------------------------------- |
| children | node                                                                                                                                                                           | true     | -                       | Body content of the button (an icon).                     |
| kind     | [ Icon.types.kind.DEFAULT, Icon.types.kind.PRIMARY, Icon.types.kind.SECONDARY, Icon.types.kind.DESTRUCTIVE, Icon.types.kind.FLAT, Icon.types.kind.MINOR, Icon.types.kind.LINK] | false    | Icon.types.kind.DEFAULT | The visual style of the button.                           |
| size     | [ Icon.types.size.SMALL, Icon.types.size.MEDIUM, Icon.types.size.LARGE]                                                                                                        | false    | Icon.types.size.MEDIUM  | Size of the button (font size, min-height, padding, etc). |

### Button.Link

| Prop             | Type                                                                                                                                                                           | required | default                | Description                                                                                         |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ---------------------- | --------------------------------------------------------------------------------------------------- |
| a11yText         | string                                                                                                                                                                         | false    | null                   | Descriptive a11y text for assistive technologies. By default, text from children node will be used. |
| children         | node                                                                                                                                                                           | true     | -                      | Body content of the button.                                                                         |
| href             | string                                                                                                                                                                         | true     | -                      | Url for the link.                                                                                   |
| icon             | node                                                                                                                                                                           | false    | null                   | An icon to be included to the left of children content.                                             |
| isDisabled       | bool                                                                                                                                                                           | false    | false                  | If the button is disabled.                                                                          |
| kind             | [ Link.types.kind.DEFAULT, Link.types.kind.PRIMARY, Link.types.kind.SECONDARY, Link.types.kind.DESTRUCTIVE, Link.types.kind.FLAT, Link.types.kind.MINOR, Link.types.kind.LINK] | false    | Link.types.kind.LINK   | The visual style of the button.                                                                     |
| size             | [ Link.types.size.SMALL, Link.types.size.MEDIUM, Link.types.size.LARGE]                                                                                                        | false    | Link.types.size.MEDIUM | Size of the button (font size, min-height, padding, etc).                                           |
| shouldOpenNewTab | bool                                                                                                                                                                           | false    | false                  | Whether the link should open a new tab.                                                             |
| suffixIcon       | node                                                                                                                                                                           | false    | <NewTabIcon />         | Size of the button (font size, min-height, padding, etc).                                           |

<!-- end: Autogenerated - do not modify -->
<!-- content -->

## Button

The `<Button>` component is a fully accessible button intended for use typically as a skeuomorphic button, but many visual styles (kinds) are available.

For buttons with a label that is only an icon, the `<Button.Icon>` component is provided. For typical close buttons, `<Button.Close>` is provided.

It is rendered as a `<button>` element by default, but can also be rendered as a generic `<span>`, via the `<RawButton>` if global CSS conflicts are an issue (when `isSemantic` prop is set to `false`).

### Usage

For a basic button

```jsx
import Button from "@paprika/button";

<Button onClick={clickHandler}>Button label</Button>;
```

Or an Icon button

```jsx
import Button from "@paprika/button";
import InfoIcon from "@paprika/icon/lib/InfoCircle";

<Button.Icon onClick={clickHandler}>
  <InfoIcon />
</Button.Icon>;
```

Or a Close button

```jsx
import Button from "@paprika/button";

<Button.Close onClick={clickHandler} />;
```

<!-- eoContent -->

## Links

- [Storybook Showcase](https://paprika.highbond.com/?path=/story/buttons-button--showcase)
- [GitHub source code](https://github.com/acl-services/paprika/tree/master/packages/Button/src)
- [Create GitHub issue](https://github.com/acl-services/paprika/issues/new?label=[]&title=@paprika/button%20[help]:%20your%20short%20description&body=%0A%23%20Help%20wanted%0A%0A%23%23%20Please%20write%20your%20question.%0A*A%20clear%20and%20concise%20description%20of%20what%20the%20question%20is*%0A%0A%23%23%20Additional%20context%0A*Add%20any%20other%20context%20or%20screenshots%20about%20your%20question%20here.*%0A)
- [CHANGELOG](https://github.com/acl-services/paprika/tree/master/packages/Button/CHANGELOG.md)