Building user-customizable themes with Tailwind CSS

A little while ago I was asked to to build a “white-label” feature into an existing app. Their customers can now customize the app to match their brand without touching code.

It will look a little something like this:

This article walks through how I build a custom theme system using Tailwind CSS and the OKLCH color space. The basics for this feature I extracted and is available on GitHub.

The approach I took generates an entire color palette from a single value, instead of managing eleven different color stops manually. Sounds complicated? It really is quite simple. Let me show you.

Tailwind allows defining custom colors using the @theme directive (these can then be used normally, e.g. text-brand-500 and bg-brand-50/60). Rather than hardcoding hex values, use CSS variables that change at runtime.

Here is the setup in app/assets/tailwind/application.css:

@import "tailwindcss";

@theme {
  --color-brand-50: oklch(0.99 0.01 var(--color-value));
  --color-brand-100: oklch(0.98 0.02 var(--color-value));
  --color-brand-200: oklch(0.94 0.04 var(--color-value));
  --color-brand-300: oklch(0.86 0.08 var(--color-value));
  --color-brand-400: oklch(0.74 0.14 var(--color-value));
  --color-brand-500: oklch(0.60 0.18 var(--color-value));
  --color-brand-600: oklch(0.52 0.16 var(--color-value));
  --color-brand-700: oklch(0.44 0.14 var(--color-value));
  --color-brand-800: oklch(0.36 0.12 var(--color-value));
  --color-brand-900: oklch(0.26 0.08 var(--color-value));
  --color-brand-950: oklch(0.16 0.04 var(--color-value));
}

Notice the same --color-value variable? By changing this one variable, all eleven shades update automatically. The lightness and chroma values stay consistent (for a harmonious palette). 🌈

Use these colors in your templates like any other Tailwind color:

<nav class="bg-brand-50 border-brand-100">
  <span class="text-brand-600">Custom Theme</span>
</nav>

OKLCH?

But wait… OKLCH? What is that? OKLCH is a modern color space that separates color into three components: lightness, chroma and hue. This makes it a perfect choice for generating color palettes (Tailwind CSS changed to OKLCH internally as well since v4, iirc).

Take the brand-500 color from the example above:

oklch(0.60 0.18 var(--color-value))

So:

0.60 is the lightness. A value of 0 is black, 1 is white. This color is medium brightness.
0.18 is the chroma (or color saturation). Higher values are more vibrant.
var(--color-value) is the hue angle in degrees (0-360). This is what changes when you update the theme and defined initially in the style-element.

The beauty of OKLCH is that lightness and chroma remain constant across the palette. Only the hue changes. This means your brand color can shift from red to blue to green while maintaining the same visual weight and saturation at each shade level.

Setting up the HTML

In your layout, add a style tag with the default theme value:

<head>
  <style data-theme>
    :root { --color-value: 60; }
  </style>
  <%= stylesheet_link_tag "tailwind", "data-turbo-track": "reload" %>
  <%= javascript_importmap_tags %>
</head>

The default value of 60 is a sorta yellow-green hue. You can change it however you want.

Wiring up the theme controller

I just added this Stimulus controller for this demo (the client’s app worked a bit different).

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static targets = ["value"]

  initialize() {
    this.style = document.querySelector('style[data-theme]')
  }

  update(event) {
    const value = event.target.value

    this.style.textContent = `:root { --color-value: ${value}; }`
    this.valueTarget.textContent = value
  }
}

The controller finds the existing style tag marked with data-theme and updates its content. This triggers a cascade: the CSS variable changes, all the brand colors are recalculated and the entire app recolors instantly. ✨

The demo interface

The example includes a simple slider to demonstrate the feature:

<div class="flex items-center gap-4 px-6 py-4 border-b border-brand-200" data-controller="theme">
  <span class="text-sm text-brand-700">Theme</span>
  <input type="range" min="0" max="360" value="60" data-action="theme#update" class="w-32 accent-brand-600">
  <span data-theme-target="value" class="text-sm text-brand-500">60</span>
</div>

<p class="mt-2 p-6 text-brand-900">Move the slider above to change the theme color.</p>

<ul class="flex gap-4 p-6">
  <li class="size-16 rounded-lg bg-brand-50 border border-brand-200"></li>
  <li class="size-16 rounded-lg bg-brand-100 border border-brand-200"></li>
  <li class="size-16 rounded-lg bg-brand-200 border border-brand-200"></li>
  <!-- … all the way to brand-950 -->
</ul>

User-selected themes

While this approach was built for a white-label app, it works equally well for user-customizable themes.

The technique is flexible. You could extend it to store multiple theme variables: primary color, secondary color, accent color. Each would be a separate CSS variable that users can customize independently.

Pretty cool, right?

推荐订阅源