Theme Helper

To make managing the active theme easier, we provide a helper class to get, set and toggle the theme. Additionally, you can provide callbacks for when the theme gets changed!

Usage

'Read the “', Usage, '” section'

Caution

The ThemeHelper can only be used client-side (in <script> tags).

script.ts

import { ThemeHelper } from 'studiocms:ui/utils';

// Instanciate a new helper
const themeHelper = new ThemeHelper();

// Get the current theme. (One of `dark`, `light` or `system`)
const theme = themeHelper.getTheme();

// Get the current theme but resolve the actual theme if `system` is selected
const resolvedTheme = themeHelper.getTheme(true);

// Set the theme to light
themeHelper.setTheme('light');

// Toggle the theme
themeHelper.toggleTheme();

// Register an element that should act as a toggle
const toggleButton = document.querySelector<HTMLButtonElement>('#toggle-button');
themeHelper.registerToggle(toggleButton);

Listening for theme changes

'Read the “', Listening for theme changes, '” section'

Using the ThemeHelper class, you can listen to theme changes! This is useful when you have logic that needs to run whenever the color scheme changes, for example in a three.js canvas where you need to change an image (*cough cough* our login page *cough*).

script.ts

import { ThemeHelper } from 'studiocms:ui/utils';

// Instanciate a new helper
const themeHelper = new ThemeHelper();

// Add a callback that gets called when the theme changes
themeHelper.onThemeChange((newTheme) => {
  // Your logic here!
});

Here’s a live example: Change the theme via the option in the top-right corner of your screen. If you’re on mobile, open the navbar and scroll all the way down. After you’ve changed the theme, check the text below:

Preview

Theme hasn’t changed yet.

Code

<span id='theme-listener-output'>
  Theme hasn't changed yet.
</span>

Script Tag

import { ThemeHelper, type Theme } from 'studiocms:ui/utils';

// Instanciate a new helper
const themeHelper = new ThemeHelper();

const outputSpan = document.querySelector<HTMLSpanElement>('#theme-listener-output')!;

// Add a callback that gets called when the theme changes
themeHelper.onThemeChange((newTheme: Theme, oldTheme: Theme) => {
  // Your logic here!
  outputSpan.textContent = `Theme is now: ${newTheme}! (Before: ${oldTheme})`;
});

Since @studiocms/ui is compatible with Starlight’s theme system, this even picks up on those changes.

Remembering a users theme selection

'Read the “', Remembering a users theme selection, '” section'

One of the few things the ThemeHelper does not do is saving the users theme preference. This is by design, since we don’t want to force websites operating in the EU (and other GDPR-enforcing countries) to have to add a cookie notice just for a UI library. Instead, implementation of this functionality is up to the developers themselves.

As a starting point, here’s a barebones example of how to implement this:

Script Tag

import { ThemeHelper, type Theme } from 'studiocms:ui/utils';

const themeHelper = new ThemeHelper();

themeHelper.onThemeChange((newTheme: Theme) => {
  localStorage.setItem('theme-selection', newTheme);
});

If you want to go even further, you can store this information in a cookie to retrieve it server-side.