Skip to main content
Light Dark System
Get ready for more awesome! Web Awesome, the next iteration of Shoelace, is on Kickstarter. Read Our Story

Integrating with Astro

This page explains how to integrate Shoelace with an Astro app.

SSR and client scripts

In the following tutorial you will notice that Shoelace cannot be imported in the frontmatter of Astro files. This is because Shoelace relies on globals from the DOM to be present.

There is a Lit + Astro integration for SSR , however it will not work with Shoelace in its current state due to some reliance on DOM APIs that aren’t shimmed. We are working to resolve this.

Instructions - Astro 4.11.3

  • Node: v18.17.1 or v20.3.0 or higher. ( v19 is not supported.)
  • Astro: 4.11.3
  • Shoelace: 2.15.1

To get started using Shoelace with Astro, the following packages must be installed.

npm install @shoelace-style/shoelace rollup-plugin-copy

Importing components

In /src/pages/index.astro, set the base path and import Shoelace.

---
// import default stylesheet
import "@shoelace-style/shoelace/dist/themes/light.css";
---

<html>
  <body>
    <sl-button>Button</sl-button>
  </body>
</html>

<script>
  import "@shoelace-style/shoelace"
</script>

You only have to import in the main index.astro file. The components can be used anywhere throughout the project.

Customizing animations

In /src/pages/index.astro, set custom animations after the Shoelace import.

---
import { setBasePath } from "@shoelace-style/shoelace/dist/utilities/base-path.js";
setBasePath("dist/assets");
---

<html>
  <body>
    <sl-tooltip content="This is a tooltip">
      <sl-button>Hover Me</sl-button>
    </sl-tooltip>
  </body>
</html>

<script>
  import "@shoelace-style/shoelace"

  const duration = 3000;
  import { setDefaultAnimation } from "@shoelace-style/shoelace/dist/utilities/animation-registry.js";
  
  setDefaultAnimation("tooltip.show", {
  keyframes: [
   { opacity: 0, scale: 0.8 },
   { opacity: 1, scale: 1 },
  ],
    options: { duration: duration, easing: "ease" },
  });
</script>