Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 37 ยท Components and Reuse

Base and Component Layers with @apply

Add your own CSS to Tailwind v4 safely: @layer base and components, @apply, preflight, how utilities override component classes and when to avoid @apply.

Even in a utility-first project you will sometimes write real CSS: default styles for headings and links, a .btn class for a CMS, or a rule for a library you do not control. Tailwind has a clear place for each kind of custom CSS, based on CSS cascade layers. Get the layer right and your CSS will always lose to utilities when it should, so you never fight specificity.

The layers

Tailwind v4 organizes its CSS in native cascade layers, in this order (later layers win):

flowchart LR
  A["theme<br/>variables"] --> B["base<br/>preflight + defaults"] --> C["components<br/>your classes"] --> D["utilities<br/>px-4, flex ..."]

Utilities always beat components, which beat base, regardless of selector specificity.

You add your own rules with @layer:

  • @layer base for element defaults (h1, a, body).
  • @layer components for reusable classes such as .btn and .card.
  • Utilities you write yourself use @utility (covered in Custom Utilities and Variants).

Preflight: what the base layer already does

Tailwind includes a reset called preflight. It removes default margins, makes headings and lists unstyled, sets box-sizing: border-box, makes images and videos display: block; max-width: 100%, and resets form controls. That is why a bare <h1> has no size or weight until you add text-2xl font-bold. If you are surprised that your list has no bullets, that is preflight. Restore it where you need it with list-disc or by writing base styles.

@layer base

Use it to give plain HTML sensible defaults, which is especially useful for rich text where you cannot add classes to each element.

Default styles for headings and links

Because h1 and a live in the base layer, a utility on a specific element still wins: <h1 class="text-5xl"> is larger, with no specificity battle.

@layer components and @apply

@apply inlines the declarations of utilities into your own rule. It is the bridge between the utility vocabulary and a named class.

A .btn component class and utility overrides

The last button shows the layer order at work: rounded-full and bg-emerald-600 are utilities, so they beat the .btn rule even though .btn has the same specificity. In older CSS you would need !important or a more specific selector.

@apply accepts variants too: @apply hover:bg-slate-700 md:px-6 dark:bg-slate-900. Add !important at the end of the list (or ! per utility in v4) to force a declaration.

Using theme values with theme() and var()

Because the theme is made of CSS variables, you rarely need a special function. Write var(--color-brand-500) or calc(var(--spacing) * 4). The older theme(colors.brand.500) function still works for compatibility, but var() is the recommended v4 way and keeps the same value you would see in DevTools.

Should you use @apply?

Be honest about the tradeoffs. @apply is perfectly fine, but it has costs:

  • You are back to inventing class names, and a naming convention to maintain.
  • Styles move away from the element, which is the part of utility-first people value.
  • Component classes do not know about the HTML around them. Template-level components (see Reusing Styles with Components) are usually more flexible.
  • In bundlers where your CSS is split into files (Vue, Svelte scoped styles), @apply needs @reference to access the theme: put @reference "../app.css"; at the top of that style block.

Good uses: rich-text defaults, styling that must be in a stylesheet, and small projects with no template engine. Weak use: moving every long class list into a .something because it looks tidy.

Do not put @apply rules outside a layer unless you know why. Unlayered CSS beats every cascade layer, including utilities, so an unlayered .btn { background: red } would defeat bg-indigo-600 on the same element.

Your own CSS next to Tailwind

You can mix ordinary CSS freely. A few practical patterns:

CSS
@import "tailwindcss";

/* 1. A global rule that is not a utility */
@layer base {
  html { scroll-behavior: smooth; }
  :focus-visible { outline-color: var(--color-indigo-500); }
}

/* 2. A component with nested selectors */
@layer components {
  .prose-lite a { @apply underline decoration-indigo-300; }
  .prose-lite :where(p + p) { @apply mt-4; }
}

Use :where() to keep specificity at zero for selectors inside components, so utilities can override them easily.

Styling CMS-like content from outside

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In what order do the layers win, from weakest to strongest?

    Later layers win, so utilities override components, which override base.
  2. 2. Why is a hand-written, unlayered .btn { background: red; } risky?

    Cascade layers lose to unlayered styles, so your rule would override utilities such as bg-indigo-600.
  3. 3. What does preflight do?

    Preflight is Tailwind's base reset, which is why raw HTML looks unstyled until you add utilities.
  4. 4. When is @layer base most useful?

    Base styles target elements, ideal for CMS output and global defaults.

Summary

  • Custom CSS goes into @layer base (element defaults) or @layer components (reusable classes); utilities always win over both.
  • Preflight resets browser defaults, which is why raw HTML is unstyled.
  • @apply copies utilities into a rule; it suits rich-text styling and stylesheet-only cases, but template components are usually better for UI.
  • Use var(--color-...) for theme values and @reference when styles live in separate files.
  • Never leave component styles unlayered.

Next: Custom Utilities and Variants