# dds-button



<!-- Auto Generated Below -->


## Overview

The button is an interactive object that emphasizes an action.

## Usage

### Button

#### Choosing a variant

Use `primary` for the one main action in a view, `secondary` (the default) for most actions, `tertiary` and `plain` for lower-emphasis actions, and `link` when the action navigates. The `link` variant renders an anchor instead of a button.

```html
<dds-button variant="primary">Save changes</dds-button>
<dds-button>Cancel</dds-button>
```

#### Label and icon

Put the label in the default slot. A button with only an `icon` and no label has no accessible name, so set `aria-label` on the host.

```html
<dds-button icon="plus-medium">Add</dds-button>
<dds-button icon="search" aria-label="Search"></dds-button>
```

Use the `badge` slot for a small count or status shown after the label.

#### Loading and disabled

`loading` shows a spinner and blocks interaction while keeping the button's size. `disabled` prevents interaction and dims the button.

```html
<dds-button loading>Saving</dds-button>
<dds-button disabled>Unavailable</dds-button>
```



## Properties

| Property     | Attribute    | Description                                                            | Type                                                            | Default       |
| ------------ | ------------ | ---------------------------------------------------------------------- | --------------------------------------------------------------- | ------------- |
| `disabled`   | `disabled`   | Prevents interaction and dims the button.                              | `boolean`                                                       | `false`       |
| `disclosure` | `disclosure` | Shows a chevron after the label, pointing the way the button opens.    | `"down" \| "left" \| "right" \| "up" \| "up-down" \| undefined` | `undefined`   |
| `expand`     | `expand`     | Stretches the button to the full width of its container.               | `boolean`                                                       | `false`       |
| `href`       | `href`       | The destination of the link variant.                                   | `string \| undefined`                                           | `undefined`   |
| `icon`       | `icon`       | The name of an icon shown before the label.                            | `string \| undefined`                                           | `undefined`   |
| `loading`    | `loading`    | Shows a spinner and blocks interaction while work is in progress.      | `boolean`                                                       | `false`       |
| `name`       | `name`       | The name submitted with the form value.                                | `string \| undefined`                                           | `undefined`   |
| `size`       | `size`       | Which step of the size scale to render at.                             | `"l" \| "m" \| "s"`                                             | `"m"`         |
| `target`     | `target`     | Where the link variant opens its destination.                          | `string \| undefined`                                           | `undefined`   |
| `tone`       | `tone`       | The intent the button conveys.                                         | `"critical" \| "default"`                                       | `"default"`   |
| `type`       | `type`       | The native button type. Ignored by the link variant.                   | `"button" \| "reset" \| "submit"`                               | `"button"`    |
| `variant`    | `variant`    | The visual emphasis of the button. The link variant renders an anchor. | `"link" \| "plain" \| "primary" \| "secondary" \| "tertiary"`   | `"secondary"` |


## Events

| Event      | Description                          | Type                |
| ---------- | ------------------------------------ | ------------------- |
| `ddsBlur`  | Emitted when the button loses focus. | `CustomEvent<void>` |
| `ddsFocus` | Emitted when the button gains focus. | `CustomEvent<void>` |


## Slots

| Slot        | Description                             |
| ----------- | --------------------------------------- |
|             | The default slot                        |
| `"badge"`   | Slot for a badge shown after the label. |
| `"default"` | Slot for the button label.              |


## Shadow Parts

| Part     | Description                                           |
| -------- | ----------------------------------------------------- |
| `"icon"` | The leading icon.                                     |
| `"root"` | The inner `<button>` (or `<a>` for the link variant). |


## Dependencies

### Depends on

- [dds-icon](../icon)
- [dds-spinner](../spinner)

### Graph
```mermaid
graph TD;
  dds-button --> dds-icon
  dds-button --> dds-spinner
  style dds-button fill:#f9f,stroke:#333,stroke-width:4px
```

----------------------------------------------

*Built with [StencilJS](https://stenciljs.com/)*