# Button

Buttons act as a trigger for certain actions. While this is their main purpose, in some very rare cases, they can be used as links to navigate to other pages.

```tsx
import {Button} from '@gravity-ui/uikit';
```

## Appearance

There are four `Button` types in terms of appearance: basic, outlined, flat, and contrast.
The `Button` appearance is determined by the `view` property.

### Basic

`action`: The most distinctive type of `Button`. It is used for the primary action on a screen that requires the most attention.
We recommend using only one such button per page.

`normal`: Default type of `Button` designed for secondary actions or to maintain the importance of an action without drawing too much attention to it.

`raised`: Placed above the content as a floating element, usually with a fixed location.

```tsx
<Button view="action" size="l">Action</Button>
<Button view="normal" size="l">Normal</Button>
<Button view="raised" size="l">Raised</Button>
```

### Outlined

`outlined`: Used for secondary actions that require less attention. It can be used with or without a main button; in the former case, it must be an emphasized one.

`outlined-action`: Usually used as a link to another page or external resource.

This type also has semantic variations that can be used when additional semantics are needed: `outlined-info`, `outlined-success`, `outlined-warning`, and `outlined-danger`.

```tsx
<Button view="outlined" size="l">Outlined</Button>
<Button view="outlined-action" size="l">Outlined Action</Button>
<Button view="outlined-info" size="l">Outlined Info</Button>
<Button view="outlined-success" size="l">Outlined Success</Button>
<Button view="outlined-warning" size="l">Outlined Warning</Button>
<Button view="outlined-danger" size="l">Outlined Danger</Button>
<Button view="outlined-utility" size="l">Outlined Utility</Button>
```

### Flat

`flat`: Used for auxiliary actions that require the least attention. It is often used in a list of buttons or action icons (without text) in an editor.

`flat-secondary`: Less emphasized than the `flat` button. It is often used as a secondary button in dialog boxes and modal windows.

`flat-action`: Usually used as a link to another page or external resource.

It also has semantic variations that can be used where additional semantics are needed: `outlined-info`, `outlined-success`, `outlined-warning`, and `outlined-danger`.

```tsx
<Button view="flat" size="l">Flat</Button>
<Button view="flat-secondary" size="l">Flat Secondary</Button>
<Button view="flat-action" size="l">Flat Action</Button>
<Button view="flat-info" size="l">Flat Info</Button>
<Button view="flat-success" size="l">Flat Success</Button>
<Button view="flat-warning" size="l">Flat Warning</Button>
<Button view="flat-danger" size="l">Flat Danger</Button>
<Button view="flat-utility" size="l">Flat Utility</Button>
```

### Contrast

The `normal-contrast`, `outline-contrast`, and `flat-contrast` buttons highlight actions against complex background, e.g., in a banner, or against an inverse background.

```tsx
<Button view="normal-contrast" size="l">Normal Contrast</Button>
<Button view="outlined-contrast" size="l">Outlined Contrast</Button>
<Button view="flat-contrast" size="l">Flat Contrast</Button>
```

## Icons

To add an icon to a `Button`, use the [`Icon`](./Icon.md) component, which is a special wrapper for SVGs.

```tsx
<Button view="outlined" size="l">
    <Icon data={Gear} size={18} />
    Start
</Button>
<Button view="outlined" size="l">
    End
    <Icon data={Gear} size={18} />
</Button>
<Button view="outlined" size="l">
    <Icon data={Gear} size={18} />
    Both
    <Icon data={Gear} size={18} />
</Button>
<Button view="outlined" size="l">
    No text:
    <Icon data={Gear} size={18} />
</Button>
```

## States

A `Button` can have different states:

`disabled`: When the button is unavailable for some reason.

`loading`: When some asynchronous processes are running in the background.

`selected`: When the user can **Enable** and **Disable** the button.

```tsx
<Button size="l" disabled>Disabled</Button>
<Button size="l" loading>Loading</Button>
<Button size="l" selected>Selected</Button>
```

### Menu trigger

`Button` automatically changes its appearance when corresponding aria-attributes (`aria-haspopup`, `aria-expanded`) are passed:

```tsx
<Button aria-haspopup="menu" aria-expanded="true">
  Menu
</Button>
```

## Size

Use the `size` property to manage the `Button` size. The default size is `m`.

```tsx
<Button size="xs">XS Size</Button>
<Button size="s">S Size</Button>
<Button size="m">M Size</Button>
<Button size="l">L Size</Button>
<Button size="xl">XL Size</Button>
```

## Width

Use the `width` property to manage the way the `Button` behaves inside the container:

`auto`: Limits the maximum width of the `Button` by hiding the overflowing content with an ellipsis.

`max`: Matches the `Button` width to the width of the parent container, also hiding the overflowing content with an ellipsis.

## Pin

The `pin` property allows you to manage the shape of the _start_ and _end_ edges and is usually used for combining multiple buttons in a single unit.
The `pin` property value consists of the _start_ and _end_ style names separated by a hyphen, e.g., `round-brick`.
The edge styles are: `round` (default), `circle`, `brick`, and `clear`.

```tsx
<div>
    <Button view="action" size="l" pin="round-brick">Create</Button>
    <Button view="action" size="l" pin="brick-round">...</Button>
</div>
<div>
    <Button view="normal" size="l" pin="circle-clear">Start</Button>
    <Button view="normal" size="l" pin="brick-brick" selected>Center</Button>
    <Button view="normal" size="l" pin="clear-circle">End</Button>
</div>
<div>
    <Button view="outlined" pin="brick-clear">1</Button>
    <Button view="outlined" pin="clear-clear">2</Button>
    <Button view="outlined" pin="clear-clear">3</Button>
    <Button view="outlined" pin="clear-brick">4</Button>
</div>
```

## Properties

`Button` accepts any valid `button` or `a` element props in addition to these:

| Name      | Description                                                          |              Type               |     Default     |
| :-------- | :------------------------------------------------------------------- | :-----------------------------: | :-------------: |
| children  | `Button` content. You can use both text and the `<Icon/>` component. |        `React.ReactNode`        |                 |
| component | Overrides the root component                                         |       `React.ElementType`       |                 |
| disabled  | Toggles the `disabled` state                                         |            `boolean`            |     `false`     |
| href      | Pass this to make the root component a link                          |            `string`             |                 |
| loading   | Toggles the `loading` state                                          |            `boolean`            |     `false`     |
| pin       | Sets the `Button` edge style                                         |            `string`             | `"round-round"` |
| qa        | `data-qa` HTML attribute, used for testing                           |            `string`             |                 |
| selected  | Toggles the `selected` state                                         |            `boolean`            |                 |
| size      | Sets the`Button` size                                                | `"xs"` `"s"` `"m"` `"l"` `"xl"` |      `"m"`      |
| view      | Sets the `Button` appearance                                         |          `ButtonView`           |   `"normal"`    |
| width     | Controls how `Button` uses parent's space                            |        `"auto"` `"max"`         |                 |

## CSS API

| Name                                | Description               |
| :---------------------------------- | :------------------------ |
| `--g-button-text-color`             | Text color                |
| `--g-button-text-color-hover`       | Text color on hover       |
| `--g-button-background-color`       | Background color          |
| `--g-button-background-color-hover` | Background color on hover |
| `--g-button-border-width`           | Border width              |
| `--g-button-border-color`           | Border color              |
| `--g-button-border-style`           | Border style              |
| `--g-button-focus-outline-width`    | Focus outline width       |
| `--g-button-focus-outline-color`    | Focus outline color       |
| `--g-button-focus-outline-style`    | Focus outline style       |
| `--g-button-focus-outline-offset`   | Focus outline offset      |
| `--g-button-height`                 | Height (line height)      |
| `--g-button-padding`                | Side paddings             |
| `--g-button-border-radius`          | Border radius             |
| `--g-button-font-size`              | Text font size            |
| `--g-button-icon-space`             | Icon available space      |
| `--g-button-icon-offset`            | Icon offset               |