Skip to main content
Since Shoelace 2.0 Code stable Pattern stable Figma ready

Button

sl-button

Buttons represent actions that are available to the user.

Examples

Basic Button

Button
<sl-button>Button</sl-button>
sl-button Button

Variants

Use the variant attribute to set the button’s variant.

Default Primary Warning Danger
<sl-button variant="default">Default</sl-button>
<sl-button variant="primary">Primary</sl-button>
<sl-button variant="warning">Warning</sl-button>
<sl-button variant="danger">Danger</sl-button>
sl-button variant="default" Default
sl-button variant="primary" Primary
sl-button variant="warning" Warning
sl-button variant="danger" Danger

Sizes

Use the size attribute to change a button’s size.

Small Medium Large Extra large
<sl-button size="small">Small</sl-button>
<sl-button size="medium">Medium</sl-button>
<sl-button size="large">Large</sl-button>
<sl-button size="x-large">Extra large</sl-button>
sl-button size="small" Small
sl-button size="medium" Medium
sl-button size="large" Large
sl-button size="x-large" Extra large

Outline Buttons

Use the outline attribute to draw outlined buttons with transparent backgrounds.

Default Primary Warning Danger
<sl-button variant="default" outline>Default</sl-button>
<sl-button variant="primary" outline>Primary</sl-button>
<sl-button variant="warning" outline>Warning</sl-button>
<sl-button variant="danger" outline>Danger</sl-button>
sl-button variant="default" outline=true Default
sl-button variant="primary" outline=true Primary
sl-button variant="warning" outline=true Warning
sl-button variant="danger" outline=true Danger

Square Buttons

Use the square attribute to give buttons a rounded-rectangle shape.

Small Medium Large Extra large
<sl-button size="small" square>Small</sl-button>
<sl-button size="medium" square>Medium</sl-button>
<sl-button size="large" square>Large</sl-button>
<sl-button size="x-large" square>Extra large</sl-button>
sl-button size="small" square=true Small
sl-button size="medium" square=true Medium
sl-button size="large" square=true Large
sl-button size="x-large" square=true Extra large

Circle Buttons

Use the circle attribute to create circular icon buttons. When this attribute is set, the button expects a single <sl-icon> in the default slot.

<sl-button variant="default" size="small" circle>
  <sl-icon library="fa" name="fas-ellipsis-vertical" label="More options"></sl-icon>
</sl-button>

<sl-button variant="default" size="medium" circle>
  <sl-icon library="fa" name="fas-ellipsis-vertical" label="More options"></sl-icon>
</sl-button>

<sl-button variant="default" size="large" circle>
  <sl-icon library="fa" name="fas-ellipsis-vertical" label="More options"></sl-icon>
</sl-button>

<sl-button variant="default" size="x-large" circle>
  <sl-icon library="fa" name="fas-ellipsis-vertical" label="More options"></sl-icon>
</sl-button>
sl-button variant="default" size="small" circle=true
  sl-icon library="fa" name="fas-ellipsis-vertical" label="More options"
sl-button variant="default" size="medium" circle=true
  sl-icon library="fa" name="fas-ellipsis-vertical" label="More options"
sl-button variant="default" size="large" circle=true
  sl-icon library="fa" name="fas-ellipsis-vertical" label="More options"
sl-button variant="default" size="x-large" circle=true
  sl-icon library="fa" name="fas-ellipsis-vertical" label="More options"

Text Buttons

Use the text variant to create a low-emphasis plain text button that looks more like body copy. Note that text buttons have no backgrounds, borders, or padding.

Download statement

Open statement
<sl-button variant="text" size="small" href="/assets/images/wordmark.svg" download="shoelace.svg">
  <sl-icon slot="prefix" library="fa" name="arrow-down-to-bracket"></sl-icon>
  Download statement</sl-button>
<br/>
<br/>
<sl-button variant="text" size="medium" href="https://example.com/" target="_blank">Open statement
  <sl-icon slot="suffix" library="fa" name="arrow-up-right-from-square"></sl-icon>
</sl-button>
sl-button variant="text" size="small" href="/assets/images/wordmark.svg" download="shoelace.svg"
  sl-icon slot="prefix" library="fa" name="arrow-down-to-bracket"
  | Text
br
br
sl-button variant="text" size="medium" href="https://example.com/" target="_blank"
  | Text
  sl-icon slot="suffix" library="fa" name="arrow-up-right-from-square"

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 target and download attributes.

Link New Window Download Disabled
<sl-button href="https://example.com/">Link</sl-button>
<sl-button href="https://example.com/" target="_blank">New Window</sl-button>
<sl-button href="/assets/images/wordmark.svg" download="shoelace.svg">Download</sl-button>
<sl-button href="https://example.com/" disabled>Disabled</sl-button>
sl-button href="https://example.com/" Link
sl-button href="https://example.com/" target="_blank" New Window
sl-button href="/assets/images/wordmark.svg" download="shoelace.svg" Download
sl-button href="https://example.com/" disabled=true Disabled

Setting a Custom Width

As expected, buttons can be given a custom width by setting the width attribute. This is useful for making buttons span the full width of their container on smaller screens.

Small Medium Large Extra large
<sl-button variant="default" size="small" style="width: 100%; margin-bottom: 1rem;">Small</sl-button>
<sl-button variant="default" size="medium" style="width: 100%; margin-bottom: 1rem;">Medium</sl-button>
<sl-button variant="default" size="large" style="width: 100%; margin-bottom: 1rem;">Large</sl-button>
<sl-button variant="default" size="x-large" style="width: 100%;">Extra large</sl-button>
sl-button variant="default" size="small" style="width: 100%; margin-bottom: 1rem;" Small
sl-button variant="default" size="medium" style="width: 100%; margin-bottom: 1rem;" Medium
sl-button variant="default" size="large" style="width: 100%; margin-bottom: 1rem;" Large
sl-button variant="default" size="x-large" style="width: 100%;" Extra large

Prefix and Suffix Icons

Use the prefix and suffix slots to add icons.

Edit Settings Open link

Edit Settings Open link

Edit Settings Open link

Edit Settings Open link
<sl-button variant="default" size="small">
  <sl-icon slot="prefix" library="fa" name="fas-pencil"></sl-icon>
  Edit
</sl-button>

<sl-button variant="default" size="small">
  <sl-icon slot="suffix" library="fa" name="fas-gear"></sl-icon>
  Settings
</sl-button>

<sl-button variant="default" size="small">
  <sl-icon slot="prefix" library="fa" name="fas-link-horizontal"></sl-icon>
  Open link
  <sl-icon slot="suffix" library="fa" name="fas-arrow-up-right-from-square"></sl-icon>
</sl-button>


<br /><br />

<sl-button variant="default">
  <sl-icon slot="prefix" library="fa" name="fas-pencil"></sl-icon>
  Edit
</sl-button>

<sl-button variant="default">
  <sl-icon slot="suffix" library="fa" name="fas-gear"></sl-icon>
  Settings
</sl-button>

<sl-button variant="default">
  <sl-icon slot="prefix" library="fa" name="fas-link-horizontal"></sl-icon>
  Open link
  <sl-icon slot="suffix" library="fa" name="fas-arrow-up-right-from-square"></sl-icon>
</sl-button>


<br /><br />

<sl-button variant="default" size="large">
  <sl-icon slot="prefix" library="fa" name="fas-pencil"></sl-icon>
  Edit
</sl-button>

<sl-button variant="default" size="large">
  <sl-icon slot="suffix" library="fa" name="fas-gear"></sl-icon>
  Settings
</sl-button>

<sl-button variant="default" size="large">
  <sl-icon slot="prefix" library="fa" name="fas-link-horizontal"></sl-icon>
  Open link
  <sl-icon slot="suffix" library="fa" name="fas-arrow-up-right-from-square"></sl-icon>
</sl-button>


<br /><br />

<sl-button variant="default" size="x-large">
  <sl-icon slot="prefix" library="fa" name="fas-pencil"></sl-icon>
 Edit
</sl-button>

<sl-button variant="default" size="x-large">
  <sl-icon slot="suffix" library="fa" name="fas-gear"></sl-icon>
  Settings
</sl-button>

<sl-button variant="default" size="x-large">
  <sl-icon slot="prefix" library="fa" name="fas-link-horizontal"></sl-icon>
  Open link
  <sl-icon slot="suffix" library="fa" name="fas-arrow-up-right-from-square"></sl-icon>
</sl-button>


sl-button variant="default" size="small"
  sl-icon slot="prefix" library="fa" name="fas-pencil"
  | Edit
sl-button variant="default" size="small"
  sl-icon slot="suffix" library="fa" name="fas-gear"
  | Settings
br
br
sl-button variant="default"
  sl-icon slot="prefix" library="fa" name="fas-pencil"
  | Edit
sl-button variant="default"
  sl-icon slot="suffix" library="fa" name="fas-gear"
  | Settings
br
br
sl-button variant="default" size="large"
  sl-icon slot="prefix" library="fa" name="fas-pencil"
  | Edit
sl-button variant="default" size="large"
  sl-icon slot="suffix" library="fa" name="fas-gear"
  | Settings
br
br
sl-button variant="default" size="x-large"
  sl-icon slot="prefix" library="fa" name="fas-pencil"
  | Edit
sl-button variant="default" size="x-large"
  sl-icon slot="suffix" library="fa" name="fas-gear"
  | Settings

Caret

Use the caret attribute to add a dropdown indicator when a button will trigger a dropdown, menu, or popover.

Small Medium Large Extra large
<sl-button size="small" caret>Small</sl-button>
<sl-button size="medium" caret>Medium</sl-button>
<sl-button size="large" caret>Large</sl-button>
<sl-button size="x-large" caret>Extra large</sl-button>
sl-button size="small" caret=true Small
sl-button size="medium" caret=true Medium
sl-button size="large" caret=true Large
sl-button size="x-large" caret=true Extra large

Loading

Use the loading attribute to make a button busy. The width will remain the same as before, preventing adjacent elements from moving around. Clicks will be suppressed until the loading state is removed.

Default Primary Warning Danger
<sl-button variant="default" size="small" loading>Default</sl-button>
<sl-button variant="primary" size="medium" loading>Primary</sl-button>
<sl-button variant="warning" size="large" loading>Warning</sl-button>
<sl-button variant="danger" size="x-large" loading>Danger</sl-button>
sl-button variant="default" loading=true Default
sl-button variant="primary" loading=true Primary
sl-button variant="warning" loading=true Warning
sl-button variant="danger" loading=true Danger

Disabled

Use the disabled attribute to disable a button.

Default Primary Warning Danger
<sl-button variant="default" disabled>Default</sl-button>
<sl-button variant="primary" disabled>Primary</sl-button>
<sl-button variant="warning" disabled>Warning</sl-button>
<sl-button variant="danger" disabled>Danger</sl-button>
sl-button variant="default" disabled=true Default
sl-button variant="primary" disabled=true Primary
sl-button variant="warning" disabled=true Warning
sl-button variant="danger" disabled=true Danger

Styling Buttons

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. sl-button[variant="primary"]).

Pink Button
<sl-button class="pink">Pink Button</sl-button>

<style>
  sl-button.pink::part(base) {
    /* Set design tokens for height and border width */
    --sl-input-height-medium: 48px;
    --sl-input-border-width: 4px;

    border-radius: 0;
    background-color: #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: var(--sl-transition-medium) transform ease, var(--sl-transition-medium) border ease;
  }

  sl-button.pink::part(base):hover {
    transform: scale(1.05) rotate(-1deg);
  }

  sl-button.pink::part(base):active {
    border-top-color: #ad005c;
    border-right-color: #ff7ac1;
    border-bottom-color: #ff7ac1;
    border-left-color: #ad005c;
    transform: scale(1.05) rotate(-1deg) translateY(2px);
  }

  sl-button.pink::part(base):focus-visible {
    outline: dashed 2px deeppink;
    outline-offset: 4px;
  }
</style>
sl-button.pink Pink Button

css:
  sl-button.pink::part(base) {
    /* Set design tokens for height and border width */
    --sl-input-height-medium: 48px;
    --sl-input-border-width: 4px;

    border-radius: 0;
    background-color: #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: var(--sl-transition-medium) transform ease, var(--sl-transition-medium) border ease;
  }

  sl-button.pink::part(base):hover {
    transform: scale(1.05) rotate(-1deg);
  }

  sl-button.pink::part(base):active {
    border-top-color: #ad005c;
    border-right-color: #ff7ac1;
    border-bottom-color: #ff7ac1;
    border-left-color: #ad005c;
    transform: scale(1.05) rotate(-1deg) translateY(2px);
  }

  sl-button.pink::part(base):focus-visible {
    outline: dashed 2px deeppink;
    outline-offset: 4px;
  }

Component Props

Property Default Details
variant 'default'

'default' | 'primary' | 'success' | 'neutral' | 'warning' | 'danger' | 'text'

The button’s theme variant.

size 'medium'

'small' | 'medium' | 'large' | 'x-large'

The button’s size.

caret false

boolean

Draws the button with a caret. Used to indicate that the button triggers a dropdown menu or similar behavior.

disabled false

boolean

Disables the button.

loading false

boolean

Draws the button in a loading state.

outline false

boolean

Draws an outlined button.

square false

boolean

Draws a square button instead of the Teamshares default pill.

circle false

boolean

Draws a circular icon button. When this attribute is present, the button expects a single <sl-icon> in the default slot.

type 'button'

'button' | 'submit' | 'reset'

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.

name ''

string

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.

value ''

string

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.

href ''

string

When set, the underlying button will be rendered as an <a> with this href instead of a <button>.

target

'_blank' | '_parent' | '_self' | '_top'

Tells the browser where to open the link. Only used when href is present.

rel 'noreferrer noopener'

string

When using href, this attribute will map to the underlying link’s rel attribute. Unlike regular links, the default is noreferrer noopener to prevent security exploits. However, if you’re using target to point to a specific tab/window, this will prevent that from working correctly. You can remove or change the default value by setting the attribute to an empty string or a value of your choice, respectively.

download

string | undefined

Tells the browser to download the linked file as this filename. Only used when href is present.

form

string

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.

formAction
formaction

string

Used to override the form owner’s action attribute.

formEnctype
formenctype

'application/x-www-form-urlencoded' | 'multipart/form-data' | 'text/plain'

Used to override the form owner’s enctype attribute.

formMethod
formmethod

'post' | 'get'

Used to override the form owner’s method attribute.

formNoValidate
formnovalidate

boolean

Used to override the form owner’s novalidate attribute.

formTarget
formtarget

'_self' | '_blank' | '_parent' | '_top' | string

Used to override the form owner’s target attribute.

validity

Gets the validity state object

validationMessage

Gets the validation message

updateComplete A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Slots

Name Details
(default) The button’s label.
prefix A presentational prefix icon or similar element.
suffix A presentational suffix icon or similar element.

Learn more about using slots.

Events

Name Name Name React Event Details
sl-blur sl-blur sl-blur onSlBlur

Emitted when the button loses focus.

sl-focus sl-focus sl-focus onSlFocus

Emitted when the button gains focus.

sl-invalid sl-invalid sl-invalid onSlInvalid

Emitted when the form control has been checked for validity and its constraints aren’t satisfied.

Learn more about events.

Methods

Name Details
click()

Simulates a click on the button.

focus()

options: FocusOptions

Sets focus on the button.

blur()

Removes focus from the button.

checkValidity()

Checks for validity but does not show a validation message. Returns true when valid and false when invalid.

getForm()

Gets the associated form, if one exists.

reportValidity()

Checks for validity and shows the browser’s validation message if the control is invalid.

setCustomValidity()

message: string

Sets a custom validation message. Pass an empty string to restore validity.

Learn more about methods.

CSS Parts

Name Description
base The component’s base wrapper.
prefix The container that wraps the prefix.
label The button’s label.
suffix The container that wraps the suffix.
caret The button’s caret icon, an <sl-icon> element.
spinner The spinner that shows when the button is in the loading state.

Learn more about customizing CSS parts.

Dependencies

This component automatically imports the following dependencies.

  • <sl-icon>
  • <sl-spinner>