Tailwind CSS Container Queries

This plugin brings CSS container queries to Tailwind CSS v3.2+ by adding an @container class to mark an element as a query container and a set of @xs through @7xl variant utilities to style descendants conditionally based on that container’s width, rather than the viewport’s. It mirrors Tailwind’s existing responsive-variant syntax (@lg:underline reads just like lg:underline) so teams already fluent in Tailwind’s breakpoint system can pick up container queries with almost no new syntax to learn. Named containers (@container/main paired with @lg/main:underline) let a component style itself relative to a specific named ancestor when multiple nested containers are in play, and arbitrary values (@[17.5rem]:underline) cover one-off sizes outside the default scale.

As of Tailwind CSS v4.0, container queries are supported natively in the core framework, and the maintainers explicitly note in the README that this plugin is no longer required for v4 projects. It remains relevant for the substantial number of codebases still on Tailwind v3.2+ that need container-query utilities without a full v4 migration, and the repository is kept around by Tailwind Labs primarily to support that legacy version.

What You Get

• An @container utility class to mark any element as a CSS container-query container
• A full @xs through @7xl variant scale (20rem-80rem) mirroring Tailwind’s existing breakpoint naming
• Named containers (@container/name + @lg/name:) for targeting a specific ancestor when containers are nested
• Arbitrary-value container queries (@[17.5rem]:underline) for one-off sizes outside the default scale
• An @container-normal utility to remove container behavior from an element conditionally
• Configuration prefix support consistent with a project’s existing Tailwind prefix setup

Common Use Cases

• Building reusable card/widget components that adapt their layout to their container’s width, not the page viewport
• Sidebar or panel components that need different styling when narrow versus wide, independent of overall screen size
• Design-system components meant to be dropped into varying layout contexts (dashboards, grids, modals) with consistent responsive behavior
• Bridging container-query needs on Tailwind v3.2+ projects that are not yet ready to migrate to Tailwind v4

Under The Hood

Architecture - The plugin is a single-purpose Tailwind plugin (src/index.ts, ~85 lines) that registers the @container utility class and a matchVariant-based set of @{size} variants using Tailwind’s plugin API, generating the underlying CSS @container at-rules and container-name scoping for the named-container feature. Tech Stack - TypeScript, built against the Tailwind CSS v3 plugin API (tailwindcss as a peer dependency), with Jest for testing (jest/ config, tests/index.test.ts). Code Quality - The test suite (~250 lines) exercises the generated CSS output for the base container class, each named size variant, named containers, and arbitrary-value variants, giving reasonable confidence the class-to-CSS mapping stays correct across Tailwind versions; however, the project has seen low commit activity since Tailwind v4 shipped native container-query support. API Design - The plugin deliberately reuses Tailwind’s established variant syntax (@lg: mirrors lg:) so there is effectively zero new API surface for developers already familiar with Tailwind’s responsive design system to learn.