What the Heck Are @layer in Tailwind? (And How I Finally Got It)

Morteza Darzi — Tue, 13 May 2025 04:01:06 +0000

At first, I didn’t really understand what the purpose of the layers in Tailwind’s CSS system was. I saw @layer base, @layer components, and @layer utilities in examples and documentation, but I didn’t know when or why to use them, or what would happen if I ignored them completely. I was just adding my custom CSS and utility classes to the app.css file without structure, and it seemed to work—until I started running into problems with class conflicts, ordering issues, and styles not applying consistently.

Understanding the Purpose of Layers
After some deep searching and asking ChatGPT for clarity, I finally understood the concept of Tailwind's CSS layering system. It’s not just about organizing code—it has a real technical impact on how styles are interpreted and prioritized during the build process. Tailwind internally uses PostCSS, and these @layer directives are essential to ensure that custom styles merge correctly with Tailwind’s own layers, without being purged or overridden unexpectedly.

What Goes in Each Layer
The @layer base section is where you should define low-level, element-based styles—things like default typography, custom fonts, or resetting browser styles. These are similar to global HTML element rules (like body, h1, a, etc.), and they should feel like the foundation of your design system. Technically, putting your base styles here ensures Tailwind knows they're part of the base layer and avoids conflicting with component or utility layers.

Then there’s @layer components, which is the perfect place for your custom reusable class-based styles—like buttons, input fields, form groups, cards, badges, and so on. These aren’t global resets; they’re building blocks made up of utility classes. The key technical benefit here is that they are injected in the right order relative to Tailwind’s own components and utilities, and they’re also preserved during purging, because Tailwind knows to expect them.

Lastly, there’s @layer utilities, where you can define your own utility classes—small, single-purpose classes like .text-shadow or .scrollbar-hide that you use similarly to Tailwind's built-in utilities. Again, this ensures these classes are injected after components and that the cascade order respects Tailwind’s utility-first principles.

Why It Matters
What I also learned is that writing CSS outside of any @layer block can still technically work, but it breaks Tailwind’s layering system. If you define a .btn style outside of @layer components, it might get purged during production builds, or worse, get overridden by utility styles later in the cascade. So it’s not just about being organized—it’s about making sure your styles are safe, consistent, and predictable.

Technical Gotchas to Watch Out For
There are also some technical rules to watch out for. For example, never use @apply on classes that you didn’t register through a layer—especially inside utilities—because it could lead to circular references or broken builds. And be careful with overriding HTML element tags like p, h1, or body in the wrong layer—they belong in base, and doing otherwise can result in unexpected behavior.

After learning all this, I went back and reorganized my app.css file. I moved all font-face definitions and HTML element styling into @layer base, grouped my custom UI component classes into @layer components, and separated out utility-style helpers like .scrollbar-hide or .tes into @layer utilities. Now my styles load in the right order, nothing gets purged, and it’s much easier to maintain and understand the file.

Final Thoughts
In short, mastering Tailwind’s layering system in your CSS file is the key to making your custom styles work harmoniously with Tailwind’s utility-first engine. It’s not just syntax—it’s structure, safety, and sanity for your project.

Why You Should Use Only One in React Tables (and How to Add a Footer)

Morteza Darzi — Sat, 03 May 2025 05:16:59 +0000

When working with tables in React (or plain HTML), you might run into a situation where you want to display two captions: one at the top and another at the bottom. I recently faced this exact problem in my React app. Here’s what I discovered, why it happens, and how to solve it in a way that works across all browsers.

🚩 The Problem: Multiple

Elements Don’t Work Consistently
According to the HTML specification, a

must have at most one , and it must be the first child of the

element. If you try to add more than one , or place a anywhere except as the first child, browser behavior becomes unpredictable:

Chrome: Sometimes renders both captions, even if the second is after the

Firefox: Only renders the first

, and ignores any others, or those not in the correct position.

This means your table might look fine in Chrome, but the second caption will be missing in Firefox. This is because each browser implements the HTML spec in its own way, and only the first

(as the first child) is guaranteed to be shown everywhere.

🧑‍💻 My Experience
While building a React table, I tried to add a second

at the bottom for extra context. It worked in Chrome, but when I checked in Firefox, the second caption was simply not rendered. Even moving the second below the inside the

didn’t help-Firefox still ignored it. That’s when I realized this is a cross-browser issue, not a bug in my code.

✅ The Solution: Use One

+ Custom Footer
If you want a second caption or footer, don’t use a second . Instead, use a single semantic for accessibility, and render any additional content outside the table, styled as needed (especially easy with Tailwind CSS).

Here’s How You Can Do It in React + Tailwind:

function MyTable({ data, footer }) {
  return (
    <div className="overflow-x-auto">
      <table className="min-w-full border border-gray-300">
        {/* Top Caption (semantic, accessible) */}
        <caption className="caption-top text-lg font-semibold mb-2">
          Main Table Caption
        </caption>
        <thead>
          <tr>
            <th className="border-b px-4 py-2">Header 1</th>
            <th className="border-b px-4 py-2">Header 2</th>
          </tr>
        </thead>
        <tbody>
          {data.map((row, i) => (
            <tr key={i}>
              <td className="border-b px-4 py-2">{row.col1}</td>
              <td className="border-b px-4 py-2">{row.col2}</td>
            </tr>
          ))}
        </tbody>
      </table>
      {/* Custom Footer or "Second Caption" */}
      <div className="mt-2 text-center text-gray-600">{footer}</div>
    </div>
  );
}

This approach guarantees your table is accessible and looks consistent in all browsers. You can pass any ReactNode as the footer, giving you full flexibility for content and styling.

📚 References
MDN Web Docs:

element – Official documentation on correct usage and limitations of the tag.

Working With Tables in React: How to Render and Edit Fetched Data (dev.to) – A practical overview of rendering tables in React, including best practices for structure and accessibility.

💡 Takeaway
Always use only one

as the first child of your table.

For extra captions/footers, use a custom element outside the table.

Don’t trust browser quirks-write code that’s consistent and accessible everywhere.

Let me know if you’ve run into similar cross-browser issues, or if you have other table best practices to share!

DEV Community: Morteza Darzi

What the Heck Are @layer in Tailwind? (And How I Finally Got It)

Why You Should Use Only One in React Tables (and How to Add a Footer)