Button
import "@taprootio/espalier/button";
<esp-button>
Used to initiate a user action or link to another page.
Here is each of the button intents:
Use icon-position="left" for a leading icon. The default "right"
position keeps the icon trailing; both positions follow writing direction
and therefore mirror in RTL.
Slots
<esp-button> has a slot:
Default
Optional custom SVG icon. Slotted icons override the generated SVG from the icon attribute.
Attributes
<esp-button> has the following attributes:
aria-pressed
aria-pressed has a default value of undefined.
Forwards a toggle's pressed state to the inner native button. Use "true" while the controlled content is active and "false" otherwise.
incognito
incognito has a default value of false.
Renders the button with a borderless, transparent treatment for quiet icon or inline actions.
button-type
button-type has a default value of "button".
Controls the button type.
The available options are: button, submit, or reset.
The default value is button. To use a link instead of a
button, set the href attribute.
collapsed
collapsed has a default value of false.
By default, buttons take up the entire width of their parent
container. Use the collapsed attribute to shrink them to the
size of their content:
disabled
disabled has a default value of false.
Controls whether or not the button is disabled.
href
href has a default value of "".
If href is set, the button will be rendered as an anchor link pointing to the href value instead of a button.
icon-only
icon-only has a default value of false.
If true, the button only displays the icon.
icon
icon has a default value of "".
Optional icon name from the configured Espalier SVG sprite. Slotted SVG content remains supported and overrides this value.
icon-position
icon-position has a default value of "right".
Places the optional icon on the logical leading ("left") or trailing
("right") side of the label. Logical placement mirrors in RTL.
label
label has a default value of "".
The label of the button.
loading
loading has a default value of false.
Controls whether or not the button is in a loading state. The button will be disabled and show a spinner while loading is true.
target
target has a default value of "".
If the button is a link, this specifies the target browser window.
rel
rel has a default value of "".
If the button is a link, this specifies the relationship
between the current page and the linked URL. Common values
include "noopener noreferrer" for external links opened
in a new tab.
formnovalidate
formnovalidate has a default value of false.
When true and button-type is "submit", the enclosing
form is submitted without running constraint validation.
intent
intent has a default value of undefined.
The element's intent — its meaning: neutral
(no pin), or success, warning, danger, info — each pinned
to its fixed status family (blue for info), retunable per theme
via intents. On token-emitting controls a non-neutral intent pins the
filled-action pair to that family, derived over the governing
zone's theme; class-styled chrome (badges, callouts, status pills)
opts out of inline emission and renders its treatment from CSS
classes instead. An intent never repaints the surrounding zone,
which is what contexts are for. Removing the attribute restores
the element's own default intent.
context
context has a default value of undefined.
A theme-defined color zone. The selected context rebinds designer-facing roles and emits a complete, contrast-enforced semantic token table on this host for descendants to inherit.
Methods
<esp-button> has the following methods:
focus
Focus the button. Forwards focus (and any FocusOptions) to the inner
<button> (or the <a> when href is set).
traverseToClosest
Traverse up the DOM tree to find the closest element that matches the selector. This method is aware of shadow DOM boundaries and will traverse through them to find the element.
Events
<esp-button> emits the following events:
esp-clicked
esp-clicked is of type CustomEvent.
Emitted when the button is clicked.
CSS Properties
<esp-button> has the following CSS properties:
--esp-button-padding
The padding inside the button label and icon areas.
--esp-button-incognito-padding
The padding for the incognito button style.
--esp-field-background
Background color of the shared field shell. Defaults to var(--esp-color-layer-2).
--esp-field-border-color
Border color of the shared field shell. Defaults to var(--esp-color-border).
--esp-field-border-width
Border width of the shared field shell. Defaults to 1px.
--esp-field-text-color
Text color used inside the shared field shell. Defaults to var(--esp-color-text).
--esp-field-hover-bg
Hover background color of the shared field shell. Derived from --esp-field-background.
--esp-field-focus-bg
Focus background color of the shared field shell. Derived from --esp-field-background.
--esp-field-focus-shadow
Shadow color used for shared field focus treatment. Defaults to var(--esp-color-shadow).