# Tailwind CSS Container Queries Plugin for v3
> @tailwindcss/container-queries adds named, configurable, and arbitrary container query utilities to Tailwind CSS v3.2 and later 3.x projects. It is for applications that have not moved to Tailwind CSS v4, where the README states that container queries are built in.
**tailwindlabs/tailwindcss-container-queries** — A plugin for Tailwind CSS v3.2+ that provides utilities for container queries.
- Repository: https://github.com/tailwindlabs/tailwindcss-container-queries
- Stars: 1,433 · Forks: 45
- Language: TypeScript
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/tailwindlabs-tailwindcss-container-queries
## Why This Plugin Exists for Tailwind CSS v3
Container queries let a component respond to the size of its containing element instead of the viewport. That distinction matters when the same component is reused in a narrow sidebar and a wider page area. A viewport-based breakpoint can choose the wrong layout when a component's available space differs from the screen.
@tailwindcss/container-queries supplies this behavior to Tailwind CSS v3.2+ as a plugin. The package does not replace Tailwind CSS itself. It adds the `@container` class, breakpoint-style variants such as `@md:` and `@lg:`, named container variants, arbitrary sizes, and a way to remove container behavior from an element.
The package's peer dependency is `tailwindcss >=3.2.0`. Its package metadata identifies Tailwind CSS as a peer dependency rather than bundling a production version of the framework. The host project must therefore provide the compatible Tailwind CSS installation.
There is an important version boundary. The README states that Tailwind CSS v4.0 supports container queries by default, so this plugin is no longer required there. It is better understood as a migration aid for Tailwind CSS v3 projects than as a default choice for every new Tailwind CSS installation.
## The @container Variant Model
The documented data flow starts with `@container`. The class marks an element as the container whose dimensions should be evaluated. A descendant then receives a container variant such as `@lg:underline`. In the README example, the descendant is underlined when the container is larger than `32rem`.
The default breakpoints are defined under the plugin's `containers` theme setting. The supplied range runs from `@xs`, which represents a minimum width of `20rem`, through `@7xl`, which represents `80rem`. Intermediate names include `@sm` at `24rem`, `@md` at `28rem`, `@lg` at `32rem`, `@xl` at `36rem`, `@2xl` at `42rem`, and larger values through `80rem`.
This naming makes container variants resemble ordinary responsive utilities, but the reference point is different. The `lg` suffix in this usage refers to the configured minimum width for a container query. A component can use the same `@lg:` variant in several placements while each placement responds to its own container.
The README also supports one-off thresholds with arbitrary values. A class such as `@[17.5rem]:underline` applies the underline utility when the marked container exceeds `17.5rem`. This is useful when the default breakpoint scale does not match a component-specific layout requirement.
## Installing the Plugin in a Tailwind CSS v3 Project
Install the package as a development dependency, then register it in the Tailwind CSS configuration file. The repository's README gives this installation command:
```bash
npm install -D @tailwindcss/container-queries
```
After installation, add the package to the `plugins` array in `tailwind.config.js`. The README shows the CommonJS configuration form:
```js
// tailwind.config.js
module.exports = {
theme: {
// ...
},
plugins: [
require('@tailwindcss/container-queries'),
// ...
],
}
```
The package's `main` entry is `dist/index.js`, and its published files field contains `dist`. The repository build process compiles `src/index.ts` to `dist` with the `build` script and emits declarations through TypeScript during `postbuild`. Those details come from `package.json`. The README does not document a separate runtime configuration file or an installation method other than npm.
The package currently has version `0.1.1` in `package.json`. The listed releases are `v0.1.0` from 2022-10-19 and `v0.1.1` from 2023-03-31. The repository is not archived, and its last push was on 2026-05-12. The README does not state whether either release was validated against every later Tailwind CSS 3.x release, so a project should confirm the peer dependency and its existing Tailwind CSS configuration before updating.
## A First Component Using @container and @lg
The smallest documented use has an outer element marked as a container and an inner element using a variant. In the following example, the inner element becomes underlined at the plugin's `@lg` threshold, which the README maps to `32rem`:
```html
```
The generated behavior depends on the containing element's width, not on the viewport alone. For a reusable card, panel, or layout region, this lets the component react to the space allocated to it. The README presents a CSS-class interface. It does not provide a JavaScript API, browser detection layer, or runtime data store.
The plugin therefore belongs in class authoring and template construction. A class with no `@container` ancestor has no documented container reference. With multiple marked elements, the nearest relevant container relationship may matter, especially when named containers are used. The README shows the basic unnamed case but does not document a fallback rule for nested unnamed containers.
## Named Containers for Selective Queries
Named containers allow a page to define more than one query context. An element marked `@container/main` establishes the container named `main`, and a descendant uses `@lg/main:underline` to target that named container. The documented HTML is:
```html
```
This feature is useful when a layout contains regions with different responsibilities. A sidebar and a main content area can expose separate query contexts rather than forcing all descendants to rely on one broad container relationship. The naming syntax adds a name to the container class, while the breakpoint portion remains familiar.
The README documents the syntax but does not provide a dedicated section on selecting a non-nearest named container, handling repeated names, or behavior when the named container does not exist. Those cases should be checked in generated CSS and representative templates before relying on complex layouts. The documentation demonstrates `@main`, but it does not claim behavior beyond that example.
## Arbitrary Thresholds, Prefix Handling, and Container Removal
The plugin supports arbitrary container widths when a design needs a threshold outside the default scale. The following class applies an underline when the container is larger than `17.5rem`:
```html
```
Arbitrary values suit a one-off component constraint, while configured names are easier to reuse consistently. The plugin provides named default widths, so teams can add their own values through the `containers` key. The README shows this configuration:
```js
// tailwind.config.js
module.exports = {
theme: {
extend: {
containers: {
'2xs': '16rem',
},
},
},
}
```
If Tailwind CSS uses a prefix, both the container class and the utility inside the container variant must follow the project's prefix placement. The README gives this form:
```html
```
For elements that should stop participating as containers, the documented class is `@container-normal`. The README combines it with a responsive utility in `@container xl:@container-normal`. The internal CSS ordering mechanism is not explained in the README.
## Limitations and the Tailwind CSS v4 Boundary
The largest limitation is version scope. The package is for Tailwind CSS v3.2+, while the README explicitly says that Tailwind CSS v4.0 has container query support by default. Installing the plugin in a v4 project can add configuration that is no longer required.
The plugin also has a narrow purpose. It adds container-query utilities, not a complete responsive layout system, JavaScript observer, or component library. The README does not describe browser support requirements, generated CSS details, debugging commands, migration steps, or a fallback for browsers that do not support CSS container queries. It does not explain whether container size features beyond width are covered.
Another boundary is compatibility detail. The peer dependency range begins at Tailwind CSS `3.2.0`, but the repository does not document a compatibility matrix for all versions above that floor. The development setup in `package.json` uses an insiders Tailwind CSS version, which is separate from the published peer requirement. That distinction matters when checking behavior in an existing application.
For teams that need no special container breakpoints or named query contexts, the plugin may add a dependency without supplying a needed design feature. For teams on Tailwind CSS v4, the documented alternative is the framework's built-in support. For teams on v3, the plugin provides a concrete class-based way to add those utilities without replacing the rest of Tailwind CSS.
## Maintenance, License, and Adoption Cost
The repository is not archived, and its last push was on 2026-05-12. The listed release history is short: `v0.1.0` on 2022-10-19 and `v0.1.1` on 2023-03-31. The repository does not state a support policy, release cadence, changelog policy, or compatibility matrix. Its maintenance status can be described only through the archived flag and push date.
The repository uses the MIT license, and `package.json` also declares the package as MIT licensed. That identifies the stated licensing model. It does not replace review of the repository's `LICENSE` file or a project's own legal and distribution requirements.
The adoption cost for a Tailwind CSS v3 project is small in configuration terms. A team must install one development dependency, register one plugin, and add container classes where needed. The larger cost is migration planning. Existing markup may need `@container` markers, named variants, arbitrary thresholds, or prefix corrections. Moving to Tailwind CSS v4 changes the decision because container queries are already supported there, so a framework upgrade may remove the need for this package.
Before adoption, verify the Tailwind CSS version, whether the existing build accepts the plugin configuration, the configured prefix, and the breakpoints used by reusable components. Those checks are more relevant than the repository's release count.
## Conclusion
Adopt this plugin when an existing application uses Tailwind CSS v3.2 or another supported Tailwind CSS 3 release and needs component layouts based on container size. Do not add it to a Tailwind CSS v4 project, where the README states that container queries are already supported by the framework. Verify the Tailwind CSS version, configured prefix, and intended container breakpoints before upgrading the dependency or migrating to v4.
## FAQ
### How do I install @tailwindcss/container-queries?
Install it with `npm install -D @tailwindcss/container-queries`, then add `require('@tailwindcss/container-queries')` to the `plugins` array in `tailwind.config.js`. The package documents compatibility with Tailwind CSS v3.2 and newer 3.x-style project configurations.
### How do I create a container query in Tailwind CSS v3?
Add `@container` to the parent element and apply a container variant such as `@lg:underline` to a descendant. The documented `@lg` threshold is a minimum container width of `32rem`.
### Do I need @tailwindcss/container-queries with Tailwind CSS v4?
No. The README states that Tailwind CSS v4.0 supports container queries by default and that this plugin is no longer required for v4.
## Sources
- [Issues](https://github.com/tailwindlabs/tailwindcss-container-queries/issues)
- [License: MIT](https://github.com/tailwindlabs/tailwindcss-container-queries/blob/main/LICENSE)
- [README](https://github.com/tailwindlabs/tailwindcss-container-queries/blob/main/README.md)
- [Releases](https://github.com/tailwindlabs/tailwindcss-container-queries/releases)
- [tailwindlabs/tailwindcss-container-queries on GitHub](https://github.com/tailwindlabs/tailwindcss-container-queries)
---
Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/tailwindlabs-tailwindcss-container-queries