skip to content

In Tailwind CSS v4, how do you extend, override or completely replace a default theme namespace such as the colour palette or the breakpoints?

level: middleimportance: must knowfreq 19%

answer

  1. add, redeclare, or reset
  2. the initial keyword as a reset
  3. asterisk resets a whole namespace
  4. --*: initial drops the entire default theme
  5. --spacing multiplier; breakpoints in one unit

basics

~20 s

In Tailwind CSS v4, add a variable to extend a namespace, redeclare a default to override it, set one to initial to remove it, and write --color-: initial (or --: initial for everything) before your values to replace it.

solid answer

~40 s

Everything happens inside `@theme`. To **extend**, add a variable in the namespace, such as `--color-sage-600` or `--breakpoint-3xl: 120rem`; the defaults stay. To **override** one value, redeclare its name (`--breakpoint-sm: 30rem`); to remove one, set it to `initial`. To **replace** a namespace, write `--color-*: initial` first and then your own colours: every default colour utility such as `bg-red-500` disappears, including `bg-white` unless you re-add `--color-white`. `--*: initial` resets the whole default theme, so you must also redeclare `--spacing`, the single base unit that numeric spacing utilities like `p-4` multiply, or they stop generating. Keep breakpoints in one unit, `rem` like the defaults, or the variants can sort in the wrong order.

code

css · 11 lines
css
@import "tailwindcss";

@theme {
  --color-*: initial;
  --color-white: #fff;
  --color-sage-600: oklch(0.56 0.07 150);
  --color-lotus-500: oklch(0.68 0.14 350);

  --breakpoint-3xl: 120rem;
  --breakpoint-2xl: initial;
}

go deeper

for a junior

Recall that a new variable extends a namespace, the same name overrides a default, and a namespace reset uses the asterisk with initial before your own values.

for a middle

Explain what each reset removes, why bg-white disappears with the palette, and how --spacing works as the one multiplier behind numeric spacing utilities.

for a senior

Show the traps after --*: initial, missing --spacing and breakpoints, and why breakpoint units must match for the variants to sort correctly.

for a principal

Argue when a closed palette via a namespace reset is worth the friction for a codebase, versus extending defaults that teams may drift onto.

## Four operations, one directive Tailwind CSS v4 imports a default theme (`theme.css`) when you write `@import "tailwindcss"`. Your own `@theme` block is merged on top of it, and four operations cover every change you will make: | Goal | What you write | Effect | |---|---|---| | Extend | `--color-sage-600: oklch(0.56 0.07 150);` | new utilities appear; defaults stay | | Override one value | `--breakpoint-sm: 30rem;` | the same utility or variant, new value | | Remove one value | `--breakpoint-2xl: initial;` | that utility or variant is gone | | Replace a namespace | `--color-*: initial;` then your own | only your values in that namespace remain | | Replace the whole theme | `--*: initial;` then your own | no theme-driven defaults at all | There is no separate "extend" section as in v3's JavaScript config: a new name simply adds to the namespace. ## Extending and overriding Extending is the common case. A yoga-studio booking app adds its brand palette and a display font beside the defaults: - `--color-sage-600` creates `bg-sage-600`, `text-sage-600`, `border-sage-600`. - `--font-display` creates `font-display`. - `--breakpoint-3xl: 120rem` creates the `3xl:` variant. Overriding uses the same name as a default. `--breakpoint-sm: 30rem` keeps the `sm:` variant but makes it trigger at 30rem instead of the default 40rem. Setting a single variable to the `initial` keyword removes it, for example `--breakpoint-2xl: initial` when the design never uses that width. ## Replacing a namespace The asterisk form resets a whole namespace before you declare your own values: ```css @theme { --color-*: initial; --color-white: #fff; --color-sage-600: oklch(0.56 0.07 150); --color-lotus-500: oklch(0.68 0.14 350); } ``` What changes: - Every default colour utility (`bg-red-500`, `text-sky-300`, …) stops being generated, which is the point: a typo or an off-brand colour no longer compiles to anything. - `bg-black` and `bg-white` go too, because `--color-black` and `--color-white` are part of the default palette; re-add what you need. - The keyword values `transparent`, `current` and `inherit` survive, because the colour utilities handle them directly rather than reading the theme. ## Replacing the whole theme `--*: initial` resets every namespace at once. Only utilities driven by theme variables are affected; static utilities such as `flex` stay. Two things are easy to miss: 1. Numeric spacing utilities are not a list of values. In v4, `p-4` compiles to `calc(var(--spacing) * 4)`, and the default `--spacing` is `0.25rem`. After `--*: initial` there is no `--spacing`, so `p-4`, `mt-7` and `w-18` stop generating until you declare one; Tailwind's own example sets `--spacing: 4px`. 2. Changing `--spacing` rescales every numeric spacing utility at once. `4px` and the default `0.25rem` match at the default root font size, but a `px` value no longer follows the user's root font-size setting. ## Breakpoints: one unit, sorted order Breakpoint variants are generated in order of their values. Tailwind's responsive-design documentation warns that mixing units can sort them unexpectedly, so a later breakpoint's classes may override an earlier one's. The defaults are in `rem` (`--breakpoint-sm: 40rem` through `--breakpoint-2xl: 96rem`), so a custom `3xl` belongs in `rem` too. To start from scratch, `--breakpoint-*: initial` resets them all. ## Choosing between them - **Extend** when the defaults are useful and you are adding brand values. - **Override** when a default is close but not right. - **Replace a namespace** when the design system defines a closed palette and default colours would only invite drift. - **Replace everything** when a shared package defines the entire token set; then redeclare `--spacing` and any breakpoints the markup relies on. ## Checking the result A reset is silent: classes that no longer exist simply compile to nothing, and the build does not fail. After changing a namespace, verify it rather than trusting the diff: 1. Search the templates for classes from the namespace you reset, for example `bg-gray-` or `text-red-`, and decide whether each needs a replacement token. 2. Open the compiled CSS and confirm which theme variables appear on `:root`; a missing `--spacing` or `--color-white` is easy to spot there. 3. Check the generated media queries for breakpoints appear in ascending order of width. 4. Look at a page that uses `p-*`, `gap-*` and `w-*` utilities after touching `--spacing`, since a single value rescales all of them at once. Overriding is the least risky operation of the four, because every class that existed before still exists afterwards; only its value moves.

  • After `--color-*: initial`, does `bg-transparent` still work?
    Yes. The colour utilities handle `transparent`, `current` and `inherit` themselves instead of reading them from the theme, so the reset does not remove them. What the reset removes are the palette entries, including `--color-white` and `--color-black`, which you re-add if the markup uses them.
  • Why might `p-4` keep working after you replace the colour namespace but break after `--*: initial`?
    Numeric spacing utilities multiply `--spacing`: `p-4` is `calc(var(--spacing) * 4)`. Resetting `--color-*` leaves `--spacing` alone, but `--*: initial` removes it, and without a multiplier Tailwind does not generate numeric spacing utilities. Declare `--spacing` again, such as `0.25rem` or `4px`.
  • You add `--breakpoint-3xl: 1920px` beside the default breakpoints. What can go wrong?
    The defaults are in `rem`. Tailwind's docs warn that mixing units can sort the generated breakpoint variants in an unexpected order, so one breakpoint's classes may override another's. Write it as `120rem` to match.

  • Setting --color-*: initial only resets the colours you redeclare afterwards.
  • Default colour utilities are hardcoded, so a theme reset cannot remove them.
  • p-4 needs its own --spacing-4 variable declared in the theme.
  • --*: initial also removes static utilities such as flex.
  • Breakpoints can mix px and rem freely because Tailwind converts them.
  • Extending the theme in v4 still needs an extend key.

Assumes Tailwind CSS v4 (4.3.3 checked); v4 replaced the v3 JavaScript theme config with CSS-first @theme variables.