# Button (w-button)

## Description

Performs an action or renders a link with button styling.

Use button variants to match action priority, risk, and context.

[Warp component reference](https://warp-ds.github.io/docs/components/button/frameworks/elements)

## Usage

Button is used for actions. Use it when the user can submit, save, confirm, cancel, open, close, or trigger something on the current page.

Use a link instead when the user is navigating to another page. If the control should look like a button but navigate like a link, use `w-link`.

### Basic Button

```html
<w-button>Save</w-button>
```

The default `variant` is `secondary` and the default `type` is `button`.

### Variants

Choose the variant based on the action's priority and context:

- `primary`: the main action in a view or flow
- `secondary`: secondary or tertiary actions; this is the default
- `negative`: destructive or high-risk actions
- `negativeQuiet`: low-emphasis destructive actions
- `utility`: compact utility actions
- `utilityQuiet`: low-emphasis utility actions
- `quiet`: low-emphasis actions, often near other buttons
- `link`: (@deprecated) action styled like an inline link
- `pill`: circular icon-style controls
- `overlay`, `overlayQuiet`, `overlayInverted`, `overlayInvertedQuiet`: controls placed on top of media or elevated surfaces

```html
<w-button variant="primary">Publish</w-button>
<w-button variant="secondary">Cancel</w-button>
<w-button variant="negative">Delete</w-button>
<w-button variant="utility">Filter</w-button>
```

### Sizes And Width

Use `small` for compact layouts. Use `full-width` when the button should fill its parent, such as in narrow mobile layouts.

```html
<w-button variant="primary" small>Save</w-button>
<w-button variant="primary" full-width>Continue</w-button>
```

### Icon-Only Buttons

Use `variant="pill"` for circular icon-only controls. Include accessible text in the slotted content so the internal button has a name.

```html
<w-button variant="pill" icon-only>
  <w-icon name="Close"></w-icon>
  <span class="sr-only">Close</span>
</w-button>
```

### Loading

Use `loading` after the user triggers an action and the action is in progress.

```html
<w-button variant="primary" loading>Saving</w-button>
```

Keep the button text descriptive while loading. Do not rely on the loading animation alone to explain what is happening.

### Form Buttons

Use `type="submit"` to submit the containing form and `type="reset"` to reset it. Use `name` and `value` when the button value should be included in form handling.

```html
<form>
  <w-button type="submit" name="intent" value="save">Save</w-button>
  <w-button type="reset">Reset</w-button>
</form>
```

### Link Styled As Button

Use an `a` tag if you need a link that looks and behaves like a link, do not use `w-button`.

### Link Styled As Button

Use `w-link` if you need a link that looks like a button.

### Disabled Actions

Avoid disabled buttons where possible. Disabled controls often make it harder for users to understand what is missing or how to continue.

Prefer an enabled button with clear validation or explanatory feedback near the related field.

## Accessibility

Buttons must have a clear accessible name and should describe the action they perform.

### Use Descriptive Text

Prefer visible text that names the action.

```html
<w-button>Save changes</w-button>
```

Avoid vague labels when the action is not obvious from context.

```html
<!-- Avoid -->
<w-button>OK</w-button>
```

### Icon-Only Buttons

If a button does not have visible text, include text for assistive technologies in the slotted content.

```html
<w-button variant="pill">
  <w-icon name="Close"></w-icon>
  <span class="sr-only">Close</span>
</w-button>
```

The accessible text should describe the action, not the icon shape.

### Disabled Buttons

Avoid disabled buttons. A disabled control can prevent keyboard users from reaching it and often does not explain what must happen before the action becomes available.

Prefer keeping the button available and showing validation or explanatory feedback when the user tries to continue.

### Button Or Link

Use a w-button for actions on the current page. Use a w-link for navigation.

For backwards compatibility, if `href` is set, `w-button` renders a link with button styling. The accessible behavior is link behavior, even though the component looks like a button. This is deprecated behaviour and you should instead use the w-link component if you need to render a link that looks like a button.

## Examples

### Primary

<elements-example>

```html
<w-button variant="primary">Publish</w-button>
```

</elements-example>

### Secondary

<elements-example>

```html
<w-button variant="secondary">Cancel</w-button>
```

</elements-example>

### Negative

<elements-example>

```html
<w-button variant="negative">Delete</w-button>
```

</elements-example>

### Utility

<elements-example>

```html
<w-button variant="utility">Filter</w-button>
```

</elements-example>

### Quiet

<elements-example>

```html
<w-button variant="quiet">Skip</w-button>
```

</elements-example>

### Icon Only

<elements-example>

```html
<w-button variant="pill" icon-only>
  <w-icon name="Close"></w-icon>
  <span class="sr-only">Close</span>
</w-button>
```

</elements-example>

### Small

<elements-example>

```html
<w-button variant="primary" small>Save</w-button>
```

</elements-example>

### Full Width

<elements-example>

```html
<w-button variant="primary" full-width>Continue</w-button>
```

</elements-example>

### Loading

<elements-example>

```html
<w-button variant="primary" loading>Saving</w-button>
```

</elements-example>

### Link Styled As Button

<elements-example>

```html
<w-button href="/messages/new" variant="primary">New message</w-button>
```

</elements-example>

### External Link

<elements-example>

```html
<w-button href="https://example.com" target="_blank">Visit example</w-button>
```

</elements-example>

### Form Actions

<elements-example>

```html
<form>
  <w-button type="submit" name="intent" value="save">Save</w-button>
  <w-button type="reset">Reset</w-button>
</form>
```

</elements-example>

## Styling API

This component supports styling through **component tokens** (CSS custom properties with a --w-c- prefix) and **parts**.

### Parts

Use `::part(...)` from outside the component.

- `base` — the clickable element (`<button>` or `<w-link>`)

Example:

```css
w-button::part(base) {
  text-transform: uppercase;
}
```

### Component tokens

Set these on `w-button` to override visuals.

```css
w-button {
  --w-c-button-bg: var(--w-s-color-background-primary);
  --w-c-button-color: var(--w-s-color-text-inverted);
}
```

#### Layout & typography

- `--w-c-button-radius`
- `--w-c-button-font-size`
- `--w-c-button-line-height`
- `--w-c-button-font-weight`
- `--w-c-button-padding-x`
- `--w-c-button-padding-y`

#### Background

- `--w-c-button-bg`
- `--w-c-button-bg-hover`
- `--w-c-button-bg-active`

#### Text color

- `--w-c-button-color`
- `--w-c-button-color-hover`
- `--w-c-button-color-active`

#### Border

- `--w-c-button-border-width`
- `--w-c-button-border-color`
- `--w-c-button-border-color-hover`
- `--w-c-button-border-color-active`

#### Focus

- `--w-c-button-outline-width`
- `--w-c-button-outline-color`
- `--w-c-button-outline-offset`

#### Motion

- `--w-c-button-transition`

### Notes

- Variant defaults are set internally using fallbacks, so overriding tokens works across variants.
- The `quiet` boolean is supported for backwards compatibility. Prefer `variant="quiet"` going forward.
- When `loading` is set, the button is treated as disabled (no pointer interaction).

## `<w-button>` API

Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).

### Properties

| Name | Type | Default | Summary |
|-|-|-|-|
| autofocus | `boolean` | `false` | Focuses the button when it is first rendered. |
| button-class | `string \| undefined` | `-` | Deprecated class applied to the internal control. **Deprecated**: This class is applied inside the shadow DOM and is unlikely to have the desired effect. Use attributes or CSS variables to customize the appearance of the button. |
| command | `string \| undefined` | `-` | The [command HTML attribute](https://developer.mozilla.org/en-US/docs/Web/API/Invoker_Commands_API#html_attributes) for Invoker Commands. |
| commandfor | `string \| undefined` | `-` | The [commandfor HTML attribute](https://developer.mozilla.org/en-US/docs/Web/API/Invoker_Commands_API#html_attributes) for Invoker Commands. |
| disabled | `boolean` | `false` | Visually disables the button. |
| full-width | `boolean` | `false` | Makes the button fill its parent width. |
| href | `string \| undefined` | `-` | URL for rendering the button as a link. |
| icon-only | `boolean` | `false` | Marks the button as icon-only. |
| loading | `boolean` | `false` | Shows the loading state. |
| name | `string \| undefined` | `-` | Form control name. |
| quiet | `boolean` | `false` | Deprecated quiet visual treatment flag. **Deprecated**: Use `variant="quiet"` instead |
| rel | `string \| undefined` | `-` | Link relationship. |
| resetFormControl (JS only) | `resetFormControl() => void` | `-` | - |
| shadowRootOptions (JS only) | `object` | `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }` | Shadow root configuration. |
| small | `boolean` | `false` | Renders the compact button size. |
| target | `string \| undefined` | `-` | Link browsing context. |
| type | [`ButtonType \| undefined`](#buttontype-undefined) | `-` | Native button type. |
| value | `string \| undefined` | `-` | Form control value. |
| variant | [`ButtonVariant \| undefined`](#buttonvariant-undefined) | `-` | Visual style of the button. |

### Property Details

#### autofocus

Focuses the button when it is first rendered.
Applies only when the component renders a native button. Link buttons with `href` do not autofocus through this component.

- Type: `boolean`
- Default: `false`

#### button-class

**Deprecated**: This class is applied inside the shadow DOM and is unlikely to have the desired effect. Use attributes or CSS variables to customize the appearance of the button.

Deprecated class applied to the internal control
This class is applied inside the shadow DOM and is unlikely to have the desired effect. Use attributes or CSS variables to customize the button appearance.

- Type: `string | undefined`
- Default: `-`

#### command

The [command HTML attribute](https://developer.mozilla.org/en-US/docs/Web/API/Invoker_Commands_API#html_attributes) for Invoker Commands.

- Type: `string | undefined`
- Default: `-`

#### commandfor

The [commandfor HTML attribute](https://developer.mozilla.org/en-US/docs/Web/API/Invoker_Commands_API#html_attributes) for Invoker Commands.

- Type: `string | undefined`
- Default: `-`

#### disabled

Visually disables the button.
Disabled buttons are discouraged because they can hide the reason an action is unavailable.

- Type: `boolean`
- Default: `false`

#### full-width

Makes the button fill its parent width.
Useful in narrow layouts where the button should span the available inline space.

- Type: `boolean`
- Default: `false`

#### href

URL for rendering the button as a link.
When set, the component renders `w-link` instead of a native `button`.

- Type: `string | undefined`
- Default: `-`

#### icon-only

Marks the button as icon-only.
Use this when the button has no visible text. Include accessible text in the slotted content so the internal button has a name.

- Type: `boolean`
- Default: `false`

#### loading

Shows the loading state.
Use after the user has triggered an action and the action is in progress.

- Type: `boolean`
- Default: `false`

#### name

Form control name.
Used when the button participates in form handling.

- Type: `string | undefined`
- Default: `-`

#### quiet

**Deprecated**: Use `variant="quiet"` instead

Deprecated quiet visual treatment flag
Use `variant="quiet"` instead.

- Type: `boolean`
- Default: `false`

#### rel

Link relationship.
Passed to the rendered link when `href` is set. If `target="_blank"` is set and `rel` is omitted, `noopener` is used.

- Type: `string | undefined`
- Default: `-`

#### resetFormControl (JS only)



- Type: `resetFormControl() => void`
- Default: `-`

#### shadowRootOptions (JS only)

Shadow root configuration.
Delegates focus from the host to the internal control.

- Type: `object`
- Default: `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }`

#### small

Renders the compact button size.
Use this in dense layouts where the default button size is too large.

- Type: `boolean`
- Default: `false`

#### target

Link browsing context.
Passed to the rendered link when `href` is set.

- Type: `string | undefined`
- Default: `-`

#### type

Native button type.
Controls whether the internal button behaves as a regular button, submits a form, or resets a form. Defaults to `button`.

- Type: [`ButtonType | undefined`](#buttontype-undefined)
- Default: `-`

#### value

Form control value.
Used with `name` when the button participates in form handling. Resets to its initial value when the form is reset.

- Type: `string | undefined`
- Default: `-`

#### variant

Visual style of the button.
Defaults to `secondary`. Use the variant that matches the action priority, risk, and placement.

- Type: [`ButtonVariant | undefined`](#buttonvariant-undefined)
- Default: `-`

### Types

#### ButtonType | undefined

`'button' | 'submit' | 'reset' | undefined`

#### ButtonVariant | undefined

`'negative' | 'primary' | 'secondary' | 'negativeQuiet' | 'utility' | 'quiet' | 'utilityQuiet' | 'overlay' | 'overlayInverted' | 'overlayQuiet' | 'overlayInvertedQuiet' | 'pill' | 'link' | undefined`

