Prepend to Default Theme Variable

[alexschcom]

Hey there,

I'm trying to use a custom font. I'd like to use the value of font-sans as the fallback and I don't want to create a separate utility class (like font-main). I know I can't do

@theme inline {
  --font-sans: "Space Grotesk", var(--font-sans);
}

as that creates a cyclic dependency --

Custom properties are left almost entirely unevaluated, except that they allow and evaluate the var() function in their value. This can create cyclic dependencies where a custom property uses a var() referring to itself, or two or more custom properties each attempt to refer to each other.

Is there any way I can prepend the name of my custom font to font-sans?

Thanks in advance!

[wongjn]

You could consider adding the raw default value into the definition manually:

@theme {
  --font-sans: "Space Grotesk", ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
}

[Omrigotlieb]

I don’t think there’s a built-in way to prepend to the existing --font-sans by referencing var(--font-sans) inside its own definition, because that creates a cycle.

The straightforward Tailwind v4 approach is to redefine --font-sans with your custom font first, then copy Tailwind’s default fallback stack after it. The docs show that font-sans is driven by --font-sans, and they also show the default stack in theme.css.

@import "tailwindcss";

@theme {
  --font-sans: "Space Grotesk", ui-sans-serif, system-ui, sans-serif,
    "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
}

[manimovassagh]

You're right that you can't self-reference a CSS custom property — that's a spec limitation, not a Tailwind one.

The trick in Tailwind v4 is to use @theme inline with the default font-sans fallback stack hardcoded. You can grab the default value from Tailwind's source (it's the standard system font stack):

@theme inline {
  --font-sans: "Space Grotesk", ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
}

This effectively prepends your font to the sans stack. The inline keyword prevents Tailwind from generating a separate CSS variable declaration, so it gets inlined directly into the utility.

If you want to keep it DRY and avoid duplicating the fallback stack, another approach is to define a separate variable for the fallback:

@theme {
  --font-sans-fallback: ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
  --font-sans: "Space Grotesk", var(--font-sans-fallback);
}

This avoids the cyclic dependency because --font-sans references --font-sans-fallback (a different variable), not itself. Then font-sans in your markup will resolve to "Space Grotesk" followed by the full system fallback stack.