CSS Variables + TailwindCSS

TailwindCSS excels at rapid frontend development, but its HTML-embedded styles can complicate customization. CSS variables (custom properties) offer powerful style control, making them ideal for easier theming and maintenance with TailwindCSS.

Using CSS Variables in Your Code

For flexibility and maintainability, especially across components and themes, define CSS variables using vanilla CSS when working with TailwindCSS. This makes your theme more dynamic.

From theme() to CSS Variables

When migrating from Tailwind v3 to v4, define styles directly with CSS variables instead of `theme()`. See this transition example:

.btn {
  background-color: var(--color-primary);
  /*
     Instead of using Tailwind’s v3 method:
     background-color: theme('colors.primary.DEFAULT');
  */
}

This method streamlines style management for large, theme-customizable projects. It avoids frequent Tailwind config changes for color adjustments and ensures consistent design through shared CSS variables.

Using CSS Variables with Tailwind Utilities

If Tailwind utilities are configured with CSS variables (details below), you can use them directly. For instance, a `bg-primary` button will inherit `--color-primary` if defined. When a variable isn't part of a utility class, Tailwind offers arbitrary value utilities.

Tailwind Arbitrary Values and CSS Variables

Arbitrary values let you directly reference CSS variables within utility classes. Here's an example for `text-color`:

<div class="text-[var(--alt-color)]">
  Custom Text Color
</div>

`--alt-color` can be any defined CSS variable.

You can learn more about arbitrary values in the TailwindCSS documentation.

Setting CSS Variables with PHP

CSS variables combined with TailwindCSS are useful for passing dynamic PHP values into styles. As Tailwind doesn't support server-side dynamic values at request time, use a CSS variable with PHP to calculate and assign values. Example: a gallery component adjusting to thumbnail sizes:

<div id="gallery" ...>
  <div
    class="grid grid-rows-[auto_var(--thumbs-size)]"
    style="--thumbs-size: <?= $smallWidth ?>px;"
  >
    <!-- Gallery Content -->
  </div>
</div>

Here, `--thumbs-size` dynamically sets the grid row size, getting its value from the `$smallWidth` PHP variable. This bridges server-side logic with front-end styling.

Configuring Tailwind for CSS Variables

How you configure Tailwind to recognize your CSS variables depends on the version you are using.

Tailwind v4 (Hyvä 1.4.0 and newer)

Tailwind v4 natively uses CSS variables, requiring no special configuration. Main color variables are declared in `tailwind-source.css` via the `@theme` directive and can reference other variables:

@theme {
    --color-bg: var(--color-primary-lighter);
    --color-fg: var(--color-primary-darker);
    --color-fg-secondary: var(--color-primary);
    --color-surface: var(--color-white);
}

For `@theme` details, see the Tailwind Docs: https://tailwindcss.com/docs/functions-and-directives#theme-directive

Tailwind v3 (Hyvä 1.3.x and earlier)

Tailwind v3's `tailwind.config.js` also supports CSS variables, but careful configuration is needed to retain full Tailwind features like opacity modifiers.

const { twProps, mergeTailwindConfig } = require('@hyva-themes/hyva-modules');
const colors = require("tailwindcss/colors");

module.exports = mergeTailwindConfig({
    theme: {
        extend: {
            colors: twProps({
                primary: {
                    lighter: colors.blue["600"],
                    DEFAULT: colors.blue["700"],
                    darker: colors.blue["800"],
                },
            })
        }
    }
})

// Example with twVar for a single value
lighter: twVar('primary-lighter', colors.blue["600"]),