Themes

Shoelace is designed to be highly customizable through pure CSS. Out of the box, you can choose from a light or dark theme. Alternatively, you can design your own theme.

A theme is nothing more than a stylesheet that uses the Shoelace API to define design tokens and apply custom styles to components. To create a theme, you will need a decent understanding of CSS, including CSS Custom Properties and the ::part selector.

Theme Basics

All themes are scoped to classes using the sl-theme-{name} convention, where {name} is a lowercase, hyphen-delimited value representing the name of the theme. The included light and dark themes use sl-theme-light and sl-theme-dark, respectively. A custom theme called “Purple Power”, for example, would use a class called sl-theme-purple-power

All selectors must be scoped to the theme’s class to ensure interoperability with other themes. You should also scope them to :host so they can be imported and applied to custom element shadow roots. 

:host,
.sl-theme-purple-power {
  /* ... */
}

Activating Themes

To activate a theme, import it and apply the theme’s class to the <html> element. This example imports and activates the built-in dark theme. 

<html class="sl-theme-dark">
  <head>
    <link rel="stylesheet" href="path/to/shoelace/dist/themes/dark.css" />
  </head>

  <body>
    ...
  </body>
</html>

Using Multiple Themes

You can activate themes on various containers throughout the page. This example uses the light theme with a dark-themed sidebar. 

<html>
  <head>
    <link rel="stylesheet" href="path/to/shoelace/dist/themes/light.css" />
    <link rel="stylesheet" href="path/to/shoelace/dist/themes/dark.css" />
  </head>

  <body>
    <nav class="sl-theme-dark">
      <!-- dark-themed sidebar -->
    </nav>

    <!-- light-themed content -->
  </body>
</html>

It’s for this reason that themes must be scoped to specific classes.

Creating Themes

There are two ways to create themes. The easiest way is to customize a built-in theme. The advanced way is to create a new theme from scratch. Which method you choose depends on your project’s requirements and the amount of effort you’re willing to commit to.

Customizing a Built-in Theme

The easiest way to customize Shoelace is to override one of the built-in themes. You can do this by importing the light or dark theme as-is, then creating a separate stylesheet that overrides design tokens and adds component styles to your liking. You must import your theme after the built-in theme.

If you’re customizing the light theme, you should scope your styles to the following selectors.

:root,
:host,
.sl-theme-light {
  /* your custom styles here */
}

If you’re customizing the dark theme, you should scope your styles to the following selectors.

:host,
.sl-theme-dark {
  /* your custom styles here */
}

By customizing a built-in theme, you’ll maintain a smaller stylesheet containing only the changes you’ve made. Contrast this to creating a new theme, where you need to explicitly define every design token required by the library. This approach is more “future-proof,” as new design tokens that emerge in subsequent versions of Shoelace will be accounted for by the built-in theme.

While this approach is easier to maintain, the drawback is that your theme can’t be activated independently — it’s tied to the built-in theme you’re extending.

Creating a New Theme

Creating a new theme is more of an undertaking than customizing an existing one. At a minimum, you must implement all of the required design tokens. The easiest way to do this is by “forking” one of the built-in themes and modifying it from there.

Start by changing the selector to match your theme’s name. Assuming your new theme is called “Purple Power”, your theme should be scoped like this. 

:host,
.sl-theme-purple-power {
  /* your custom styles here */
}

By creating a new theme, you won’t be relying on a built-in theme as a foundation. Because the theme is decoupled from the built-ins, you can activate it independently as an alternative to the built-ins. This is the recommended approach if you’re looking to open source your theme for others to use.

You will, however, need to maintain your theme more carefully, as new versions of Shoelace may introduce new design tokens that your theme won’t have accounted for. Because of this, it’s recommended that you clearly specify which version(s) of Shoelace your theme is designed to work with and keep it up to date as new versions of Shoelace are released.

Dark Theme

The built-in dark theme uses an inverted color scale so, if you’re using design tokens as intended, you’ll get dark mode for free. While this isn’t the same as a professionally curated dark theme, it provides an excellent baseline for one and you’re encouraged to customize it depending on your needs.

The dark theme works by taking the light theme’s color tokens and “flipping” the scale so 100 becomes 900, 200 becomes 800, 300 becomes 700, etc. Next, the luminance of each primitive was fine-tuned to avoid true black, which is often undesirable in dark themes, and provide a richer experience. The result is a custom dark palette that complements the light theme and makes it easy to offer light and dark modes with minimal effort.

To install the dark theme, add the following to the <head> section of your page.

<link rel="stylesheet" href="https://esm.sh/@teamshares/shoelace@2.1.0/cdn/themes/dark.css" />

To activate the theme, apply the sl-theme-dark class to the <html> element. 

<html class="sl-theme-dark">
  ...
</html>

Detecting the User’s Color Scheme Preference

Shoelace doesn’t try to auto-detect the user’s light/dark mode preference. This should be done at the application level. As a best practice, to provide a dark theme in your app, you should:

  • Check for prefers-color-scheme and use its value by default
  • Allow the user to override the setting in your app
  • Remember the user’s preference and restore it on subsequent logins

Shoelace avoids using the prefers-color-scheme media query because not all apps support dark mode, and it would break things for the ones that don’t.