Button
sl-button
Buttons represent actions that are available to the user.
Examples
Basic Button
<sl-button>Button</sl-button>
sl-button Button
Variants
Use the variant
attribute to set the button’s variant.
<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.
<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.
<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.
Note: Square buttons are not the standard button pattern in our Design System, and there is no Figma component for this option. Please check with the design team before using this option.
<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.
Note: Don’t use text
buttons in size large
or
x-large
. There is no visible difference between the text
button’s
medium
and large
sizes, and the x-large
size gives too mich
emphasis to the button. Please check with the design team before using these size options.
<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"
Link Buttons
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.
<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
When a target
is set, the link will receive rel="noreferrer noopener"
for
security reasons.
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.
<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.
<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.
<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.
<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.
<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"]
).
Note: In general, you shouldn’t need to do this. If you are working on a design that requires custom styling, please ensure that there’s not a standard button in the design system that would work instead. If you really do need a non-standard button, please consult the design team before implementing a custom version, so that the team can determine whether the existing pattern should be updated.
<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
Note: The following appear as options in the Properties table but are currently not part of the Teamshares Design System. Please check with the design team before using these options:
- Variants
neutral
,success
- Boolean
square
Property | Default | Details |
---|---|---|
variant
|
'default'
|
The button’s theme variant. |
size
|
'medium'
|
The button’s size. |
caret
|
false
|
Draws the button with a caret. Used to indicate that the button triggers a dropdown menu or similar behavior. |
disabled
|
false
|
Disables the button. |
loading
|
false
|
Draws the button in a loading state. |
outline
|
false
|
Draws an outlined button. |
square
|
false
|
Draws a square button instead of the Teamshares default pill. |
circle
|
false
|
Draws a circular icon button. When this attribute is present, the button expects a single
|
type
|
'button'
|
The type of button. Note that the default value is |
name
|
''
|
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 |
value
|
''
|
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
|
''
|
When set, the underlying button will be rendered as an |
target
|
— |
Tells the browser where to open the link. Only used when |
rel
|
'noreferrer noopener'
|
When using |
download
|
— |
Tells the browser to download the linked file as this filename. Only used when
|
form
|
— |
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
|
— |
Used to override the form owner’s |
formEnctype
formenctype
|
— |
Used to override the form owner’s |
formMethod
formmethod
|
— |
Used to override the form owner’s |
formNoValidate
formnovalidate
|
— |
Used to override the form owner’s |
formTarget
formtarget
|
— |
Used to override the form owner’s |
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()
|
Sets focus on the button. |
blur()
|
Removes focus from the button. |
checkValidity()
|
Checks for validity but does not show a validation message. Returns |
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()
|
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>