Button - Elements

Buttons initiate events or actions within a page, informing users of what to expect next.

AndroidreleasedElementsreleasediOSreleasedReactreleasedReact 19releasedVuereleased

Example theme:

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.

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.

Examples

Primary

html

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

Secondary

html

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

Negative

html

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

Utility

html

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

Quiet

html

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

Icon Only

html

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

Small

html

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

Full Width

html

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

Loading

html

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

Link Styled As Button

html

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

External Link

html

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

Form Actions

html

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

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`	`-`	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`	`-`	The command HTML attribute for Invoker Commands.
commandfor	`string`	`-`	The commandfor HTML attribute for Invoker Commands.
disabled	`boolean`	`false`	Visually disables the button.
full-width	`boolean`	`false`	Makes the button fill its parent width.
href	`string`	`-`	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`	`-`	Form control name.
quiet	`boolean`	`false`	Deprecated quiet visual treatment flag. Deprecated: Use `variant="quiet"` instead
rel	`string`	`-`	Link relationship.
shadowRootOptions (JS only)	`object`	`{ ...LitElement.shadowRootOptions, delegatesFocus: true, }`	Shadow root configuration.
small	`boolean`	`false`	Renders the compact button size.
target	`string`	`-`	Link browsing context.
type	`ButtonType`	`-`	Native button type.
value	`string`	`-`	Form control value.
variant	`ButtonVariant`	`-`	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
Default: -

command

The command HTML attribute for Invoker Commands.

Type: string
Default: -

commandfor

The commandfor HTML attribute for Invoker Commands.

Type: string
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
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
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
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
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
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
Default: -

variant

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

Type: ButtonVariant
Default: -

Types

ButtonType

'button' | 'submit' | 'reset'

ButtonVariant

Questions?

Feel free to ask any questions on usage in the Warp DS Slack channel: #warp-design-system

Button - Elements ​

Accessibility ​

Use Descriptive Text ​

Icon-Only Buttons ​

Disabled Buttons ​

Button Or Link ​

Usage ​

Basic Button ​

Variants ​

Sizes And Width ​

Icon-Only Buttons ​

Loading ​

Form Buttons ​

Link Styled As Button ​

Link Styled As Button ​

Disabled Actions ​

Examples ​

Primary ​

Secondary ​

Negative ​

Utility ​

Quiet ​

Icon Only ​

Small ​

Full Width ​

Loading ​

Link Styled As Button ​

External Link ​

Form Actions ​

Styling API ​

Parts ​

Component tokens ​

Layout & typography ​

Background ​

Text color ​

Border ​

Focus ​

Motion ​

Notes ​

<w-button> API ​

Properties ​

Property Details ​

autofocus ​

button-class ​

command ​

commandfor ​

disabled ​

full-width ​

href ​

icon-only ​

loading ​

name ​

quiet ​

rel ​

shadowRootOptions (JS only) ​

small ​

target ​

type ​

value ​

variant ​

Types ​

ButtonType ​

ButtonVariant ​

Questions? ​

Button - Elements

Accessibility

Use Descriptive Text

Icon-Only Buttons

Disabled Buttons

Button Or Link

Usage

Basic Button

Variants

Sizes And Width

Icon-Only Buttons

Loading

Form Buttons

Link Styled As Button

Link Styled As Button

Disabled Actions

Examples

Primary

Secondary

Negative

Utility

Quiet

Icon Only

Small

Full Width

Loading

Link Styled As Button

External Link

Form Actions

Styling API

Parts

Component tokens

Layout & typography

Background

Text color

Border

Focus

Motion

Notes

`<w-button>` API

Properties

Property Details

autofocus

button-class

command

commandfor

disabled

full-width

href

icon-only

loading

name

quiet

rel

shadowRootOptions (JS only)

small

target

type

value

variant

Types

ButtonType

ButtonVariant

Questions?