Shoelace Web Component Library

Shoelace is a library of framework-agnostic web components. Because it is built on web standards, it provides several advantages over framework-specific component libraries:

• Framework Agnostic: Works with React, Vue, Angular, or no framework at all.
• Longevity: Since it uses standard Web Components, it is not tied to the lifecycle of a specific framework version.
• Customizable: Fully stylable with CSS.
• Interoperability: You can build multiple apps using different frameworks that all share the same UI components.
• Accessibility: Built with accessibility in mind.

Shoelace is a library of web components designed with the following characteristics:

• Framework Agnostic: Works with all frontend frameworks.
• CDN Support: Can be loaded via CDNs.
• Customizable: Fully customizable using CSS.
• Theming: Includes an official dark theme.
• Accessible: Built with accessibility in mind.
• Open Source: Available under the MIT license.

The sl-card component is used to group related subjects in a container. It supports several slots to customize its layout:

• Default slot: Used for the main body content of the card.
• slot="header": Used to display titles or controls at the top of the card.
• slot="footer": Used to display actions, summaries, or other relevant content at the bottom.
• slot="image": Used to display an image at the top of the card that stretches to fit the width.

<sl-card>
  <div slot="header">Header Content</div>
  Main body content goes here.
  <div slot="footer">Footer Content</div>
</sl-card>

Shoelace is sunset

Shoelace is no longer under active development. While the library remains available under the MIT license for existing use, all new development, bug reports, feature requests, and pull requests should be directed to Web Awesome, the successor project.

• Do not open issues or pull requests here.
• Migration: If you are currently using Shoelace, follow the migration guide to move to Web Awesome.
• Successor Project: Web Awesome provides an expanded library of components, themes, utilities, and patterns.

If a tooltip is inside a container with overflow: auto, overflow: hidden, or overflow: scroll, it may be clipped.

Adding the hoist attribute forces the tooltip to use a fixed positioning strategy. This allows the tooltip to break out of the container and position itself relative to its containing block (usually the viewport).

<div style="overflow: hidden;">
  <sl-tooltip content="I am not clipped" hoist>
    <sl-button>Hover Me</sl-button>
  </sl-tooltip>
</div>

The toast stack is a singleton element managed internally by the alert component. It stacks toasts vertically and is positioned at the top-right of the viewport by default.

You can change the position of all toasts by targeting the .sl-toast-stack class in your CSS. For example, to move the stack to the top-left:

.sl-toast-stack {
  left: 0;
  right: auto;
}

Note: It is not possible to show toasts in more than one stack simultaneously.

The shift attribute prevents a popup from being clipped when it is longer than its anchor element. When enabled, the popup will shift along its axis to stay within view.

You can customize this behavior using:

• shift-padding: Sets the padding for the shift operation.
• shiftBoundary: Defines the boundary for the shift behavior.

<sl-popup placement="top" shift shift-padding="10" active>
  <span slot="anchor"></span>
  <div class="box"></div>
</sl-popup>

Shoelace components use Shadow DOM to encapsulate markup and styles. Because native <form> elements cannot see inside a shadow root, they typically cannot recognize form controls located there.

Shoelace overcomes this by intercepting the formdata and submit events. When a form is submitted, Shoelace automatically injects the values of its form controls into the FormData object.

Important Integration Note: If you are attaching your own event listeners to a <form> (e.g., for custom submission logic), you must attach them after the Shoelace form controls have been connected to the DOM. If you attach them too early, your logic may execute before Shoelace has had the chance to inject the form data or trigger validation.

Boolean props must always default to false so users can unset them via attributes. Use a no- prefix for properties that hide or disable features to maintain consistency (e.g., no-spin-buttons instead of hide-spin-buttons).

Naming Convention:

• Property: noHeader
• Attribute: no-header

Shoelace components use slots to allow you to pass content into specific areas of the component.

• Default Slot: Content placed directly inside the component tags without a slot attribute. Used for things like button labels.
• Named Slots: Content assigned to a specific location using the slot attribute (e.g., slot="prefix"). The browser automatically moves these elements to the correct position within the component's shadow DOM.

<!-- Default slot usage -->
<sl-button>Click me</sl-button>

<!-- Named slot usage -->
<sl-button>
  <sl-icon slot="prefix" name="gear"></sl-icon>
  Settings
</sl-button>