Button
<wa-button>
Buttons represent actions that are available to the user.
<wa-button>Button</wa-button>
Examples
Jump to heading
Variants
Jump to heading
Use the variant attribute to set the button's semantic variant.
<wa-button variant="neutral">Neutral</wa-button> <wa-button variant="brand">Brand</wa-button> <wa-button variant="success">Success</wa-button> <wa-button variant="warning">Warning</wa-button> <wa-button variant="danger">Danger</wa-button>
Appearance
Jump to heading
Use the appearance attribute to change the button's visual appearance.
<div class="wa-stack"> <div class="wa-gap-2xs"> <wa-button appearance="accent" variant="neutral">Accent</wa-button> <wa-button appearance="filled-outlined" variant="neutral">Filled-Outlined</wa-button> <wa-button appearance="filled" variant="neutral">Filled</wa-button> <wa-button appearance="outlined" variant="neutral">Outlined</wa-button> <wa-button appearance="plain" variant="neutral">Plain</wa-button> </div> <div class="wa-gap-2xs"> <wa-button appearance="accent" variant="brand">Accent</wa-button> <wa-button appearance="filled-outlined" variant="brand">Filled-Outlined</wa-button> <wa-button appearance="filled" variant="brand">Filled</wa-button> <wa-button appearance="outlined" variant="brand">Outlined</wa-button> <wa-button appearance="plain" variant="brand">Plain</wa-button> </div> <div class="wa-gap-2xs"> <wa-button appearance="accent" variant="success">Accent</wa-button> <wa-button appearance="filled-outlined" variant="success">Filled-Outlined</wa-button> <wa-button appearance="filled" variant="success">Filled</wa-button> <wa-button appearance="outlined" variant="success">Outlined</wa-button> <wa-button appearance="plain" variant="success">Plain</wa-button> </div> <div class="wa-gap-2xs"> <wa-button appearance="accent" variant="warning">Accent</wa-button> <wa-button appearance="filled-outlined" variant="warning">Filled-Outlined</wa-button> <wa-button appearance="filled" variant="warning">Filled</wa-button> <wa-button appearance="outlined" variant="warning">Outlined</wa-button> <wa-button appearance="plain" variant="warning">Plain</wa-button> </div> <div class="wa-gap-2xs"> <wa-button appearance="accent" variant="danger">Accent</wa-button> <wa-button appearance="filled-outlined" variant="danger">Filled-Outlined</wa-button> <wa-button appearance="filled" variant="danger">Filled</wa-button> <wa-button appearance="outlined" variant="danger">Outlined</wa-button> <wa-button appearance="plain" variant="danger">Plain</wa-button> </div> </div>
Sizes
Jump to heading
Use the size attribute to change a button's size.
<wa-button size="small">Small</wa-button> <wa-button size="medium">Medium</wa-button> <wa-button size="large">Large</wa-button>
Pill Buttons
Jump to heading
Use the pill attribute to give buttons rounded edges.
<wa-button size="small" pill>Small</wa-button> <wa-button size="medium" pill>Medium</wa-button> <wa-button size="large" pill>Large</wa-button>
Link Buttons
Jump to heading
It's often helpful to have a button that works like a link. This is possible by setting the href attribute, which will make the component render an <a> under the hood. This gives you all the default link behavior the browser provides (e.g. CMD/CTRL/SHIFT + CLICK) and exposes the rel, target, and download attributes.
<wa-button href="https://example.com/">Link</wa-button> <wa-button href="https://example.com/" target="_blank">New Window</wa-button> <wa-button href="/assets/images/logo.svg" download="shoelace.svg">Download</wa-button>
Icon Buttons
Jump to heading
When only an icon is slotted into the label slot, the button becomes an icon button. In this case, it's important to give the icon a label for users with assistive devices. Icon buttons can use any appearance or variant.
<div class="wa-cluster"> <wa-button variant="neutral" appearance="accent"><wa-icon name="house" label="Home"></wa-icon></wa-button> <wa-button variant="neutral" appearance="outlined"><wa-icon name="house" label="Home"></wa-icon></wa-button> <wa-button variant="neutral" appearance="filled"><wa-icon name="house" label="Home"></wa-icon></wa-button> <wa-button variant="neutral" appearance="plain"><wa-icon name="house" label="Home"></wa-icon></wa-button> </div>
Setting a Custom Width
Jump to heading
As expected, buttons can be given a custom width by setting the width CSS property. This is useful for making buttons span the full width of their container on smaller screens.
<wa-button size="small" style="width: 100%; margin-bottom: 1rem;">Small</wa-button> <wa-button size="medium" style="width: 100%; margin-bottom: 1rem;">Medium</wa-button> <wa-button size="large" style="width: 100%;">Large</wa-button>
Start & End Decorations
Jump to heading
Use the start and end slots to add presentational elements like <wa-icon> next to the button label.
<wa-button size="small"> <wa-icon slot="start" name="gear"></wa-icon> Settings </wa-button> <wa-button size="small"> <wa-icon slot="end" name="undo"></wa-icon> Refresh </wa-button> <wa-button size="small"> <wa-icon slot="start" name="link"></wa-icon> <wa-icon slot="end" name="arrow-up-right-from-square"></wa-icon> Open </wa-button> <br /><br /> <wa-button> <wa-icon slot="start" name="gear"></wa-icon> Settings </wa-button> <wa-button> <wa-icon slot="end" name="undo"></wa-icon> Refresh </wa-button> <wa-button> <wa-icon slot="start" name="link"></wa-icon> <wa-icon slot="end" name="arrow-up-right-from-square"></wa-icon> Open </wa-button> <br /><br /> <wa-button size="large"> <wa-icon slot="start" name="gear"></wa-icon> Settings </wa-button> <wa-button size="large"> <wa-icon slot="end" name="undo"></wa-icon> Refresh </wa-button> <wa-button size="large"> <wa-icon slot="start" name="link"></wa-icon> <wa-icon slot="end" name="arrow-up-right-from-square"></wa-icon> Open </wa-button>
Caret
Jump to heading
Use the with-caret attribute to add a dropdown indicator when a button will trigger a dropdown, menu, or popover.
<wa-button size="small" with-caret> <wa-icon name="gear" label="Settings"></wa-icon> </wa-button> <wa-button size="small" with-caret>Small</wa-button> <wa-button size="medium" with-caret>Medium</wa-button> <wa-button size="large" with-caret>Large</wa-button>
Loading
Jump to heading
Use the loading attribute to make a button busy. The width will remain the same as before, preventing adjacent elements from moving around.
<wa-button variant="brand" loading>Brand</wa-button> <wa-button variant="success" loading>Success</wa-button> <wa-button variant="neutral" loading>Neutral</wa-button> <wa-button variant="warning" loading>Warning</wa-button> <wa-button variant="danger" loading>Danger</wa-button>
Disabled
Jump to heading
Use the disabled attribute to disable a button.
<wa-button variant="brand" disabled>Brand</wa-button> <wa-button variant="success" disabled>Success</wa-button> <wa-button variant="neutral" disabled>Neutral</wa-button> <wa-button variant="warning" disabled>Warning</wa-button> <wa-button variant="danger" disabled>Danger</wa-button>
Styling Buttons
Jump to heading
This example demonstrates how to style buttons using a custom class. This is the recommended approach if you need to add additional variations. To customize an existing variation, modify the selector to target the button's variant attribute instead of a class (e.g. wa-button[variant="brand"]).
<wa-button class="pink">Pink Button</wa-button> <style> wa-button.pink::part(base) { border-radius: 6px; border: solid 2px; background: #ff1493; border-top-color: #ff7ac1; border-left-color: #ff7ac1; border-bottom-color: #ad005c; border-right-color: #ad005c; color: white; font-size: 1.125rem; box-shadow: 0 2px 10px #0002; transition: all var(--wa-transition-slow) var(--wa-transition-easing); } wa-button.pink::part(base):hover { transform: scale(1.05); } wa-button.pink::part(base):active { border-top-color: #ad005c; border-right-color: #ff7ac1; border-bottom-color: #ff7ac1; border-left-color: #ad005c; transform: translateY(1px); } wa-button.pink::part(base):focus-visible { outline: dashed 2px deeppink; outline-offset: 4px; } </style>
Slots
Jump to heading
Learn more about using slots.
| Name | Description |
|---|---|
| (default) | The button's label. |
start
|
An element, such as <wa-icon>, placed before the label. |
end
|
An element, such as <wa-icon>, placed after the label. |
Attributes & Properties
Jump to heading
Learn more about attributes and properties.
| Name | Description | Reflects | |
|---|---|---|---|
variantvariant |
The button's theme variant. Defaults to
neutral if not within another element with a variant.Type
'neutral' | 'brand' | 'success' | 'warning' | 'danger'Default
'neutral' |
|
|
appearanceappearance |
The button's visual appearance.
Type
'accent' | 'filled' | 'outlined' | 'filled-outlined' | 'plain'Default
'accent' |
|
|
sizesize |
The button's size.
Type
'small' | 'medium' | 'large'Default
'medium' |
|
|
withCaretwith-caret |
Draws the button with a caret. Used to indicate that the button triggers a dropdown menu or similar behavior.
Type
booleanDefault
false |
|
|
disableddisabled |
Disables the button. Does not apply to link buttons.
Type
booleanDefault
false |
||
loadingloading |
Draws the button in a loading state.
Type
booleanDefault
false |
|
|
pillpill |
Draws a pill-style button with rounded edges.
Type
booleanDefault
false |
|
|
typetype |
The type of button. Note that the default value is
button instead of submit, which is opposite of how native
<button> elements behave. When the type is submit, the button will submit the surrounding form.Type
'button' | 'submit' | 'reset'Default
'button' |
||
namename |
The name of the button, submitted as a name/value pair with form data, but only when this button is the submitter.
This attribute is ignored when
href is present.Type
string |
|
|
valuevalue |
The value of the button, submitted as a pair with the button's name as part of the form data, but only when this
button is the submitter. This attribute is ignored when
href is present.Type
string |
|
|
hrefhref |
When set, the underlying button will be rendered as an
<a> with this href instead of a <button>.Type
string |
|
|
targettarget |
Tells the browser where to open the link. Only used when
href is present.Type
'_blank' | '_parent' | '_self' | '_top' |
||
relrel |
When using
href, this attribute will map to the underlying link's rel attribute.Type
string | undefined |
||
downloaddownload |
Tells the browser to download the linked file as this filename. Only used when
href is present.Type
string | undefined |
||
formform |
The "form owner" to associate the button with. If omitted, the closest containing form will be used instead. The
value of this attribute must be an id of a form in the same document or shadow root as the button.
Type
string | nullDefault
null |
|
|
formActionformaction |
Used to override the form owner's
action attribute.Type
string |
||
formEnctypeformenctype |
Used to override the form owner's
enctype attribute.Type
'application/x-www-form-urlencoded' | 'multipart/form-data' | 'text/plain' |
||
formMethodformmethod |
Used to override the form owner's
method attribute.Type
'post' | 'get' |
||
formNoValidateformnovalidate |
Used to override the form owner's
novalidate attribute.Type
boolean |
||
formTargetformtarget |
Used to override the form owner's
target attribute.Type
'_self' | '_blank' | '_parent' | '_top' | string |
Methods
Jump to heading
Learn more about methods.
| Name | Description | Arguments |
|---|---|---|
click() |
Simulates a click on the button. | |
focus() |
Sets focus on the button. |
options: FocusOptions
|
blur() |
Removes focus from the button. |
Events
Jump to heading
Learn more about events.
| Name | Description |
|---|---|
blur |
Emitted when the button loses focus. |
focus |
Emitted when the button gains focus. |
wa-invalid |
Emitted when the form control has been checked for validity and its constraints aren't satisfied. |
CSS parts
Jump to heading
Learn more about CSS parts.
| Name | Description | CSS selector |
|---|---|---|
base |
The component's base wrapper. |
::part(base)
|
start |
The container that wraps the start slot. |
::part(start)
|
label |
The button's label. |
::part(label)
|
end |
The container that wraps the end slot. |
::part(end)
|
caret |
The button's caret icon, a <wa-icon> element. |
::part(caret)
|
spinner |
The spinner that shows when the button is in the loading state. |
::part(spinner)
|
Dependencies
Jump to heading
This component automatically imports the following elements. Sub-dependencies, if any exist, will also be included in this list.
Importing
Jump to heading
Autoloading components via projects is the recommended way to import components. If you prefer to do it manually, use one of the following code snippets.
Let your project code do the work! Sign up for free to use a project with your very own CDN — it's the fastest and easiest way to use Web Awesome.
To manually import this component from NPM, use the following code.
import '@awesome.me/webawesome/dist/components/button/button.js';
To manually import this component from React, use the following code.
import WaButton from '@awesome.me/webawesome/dist/react/button';
Need a hand?