Expand named container queries to all variants (@max-value/name, @min-value/name, etc.) for semantic clarity and modular extensibility

[selcukcukur]

Summary

Tailwind CSS currently supports named container queries in breakpoint-based forms such as @container name (width >= value) and @container @sm/name. This proposal advocates for extending named query support to range-based variants—including (width < value), (width >= value), and compound expressions—so that named containers can be used consistently across all container query types. This unlocks semantic clarity, modular trait composition, and teardown-safe architecture across layout systems.

Motivation

🧠 1. Semantic Clarity Across All Query Types

Named container queries like sidebar (width < 768px) or card (width >= 640px) offer immediate semantic context. This improves readability, contributor onboarding, and trait-scoped documentation—especially in large-scale design systems.

🧩 2. Trait Modularity and Teardown Safety

Named queries allow traits to be grouped by semantic domain (e.g., Flex Layout, Spacing, Sidebar, Card) and exported teardown-safely. This aligns with Tailwind’s utility-first philosophy while enabling sugar-style documentation and contributor-friendly exports.

🔄 3. Consistency Across Query Syntax

While breakpoint-based named queries (@container @sm/name) are supported, range-based queries ((width < value), (width >= value)) currently lack named support. Extending named support to these variants ensures architectural symmetry and avoids edge-case confusion when composing responsive traits.

Currently Supported

/* Applies to any container with width >= target */
@container (width >= target) {
  /* styles for unnamed container */
}

/* Applies to a container named 'name' with width >= target */
@container name (width >= target) {
  /* styles for named container */
}

Proposed

/* Applies to container named 'sidebar' when width is between value and max-value */
@container sidebar (width >= value) and (width < max-value) {
  /* styles for 'sidebar' container within a specific range */
}

/* Applies to container named 'card' when width is less than value */
@container card (width < value) {
  /* styles for 'card' container below threshold */
}

/* Applies to container named 'sidebar' when width is greater than or equal to value */
@container sidebar (width >= value) {
  /* styles for 'sidebar' container above threshold */
}

Technical Considerations

🔍 Parsing Strategy

• Extend the container query parser to support named containers in all range-based expressions.
• Normalize expressions like name (width < value) and name (width >= value) and (width < max-value) into internal query maps for consistent resolution.

✅ Backward Compatibility

• Fully backward compatible with existing container query usage.
• Named queries are opt-in, additive, and non-intrusive—ensuring zero disruption to existing setups.

🛠 Developer Experience Enhancements

• Improves autocomplete and IntelliSense in IDEs.
• Enables trait-scoped documentation and grouping in Tailwind plugins and presets.
• Encourages semantic naming conventions in layout modules.

Ecosystem Impact

• Aligns with Tailwind’s semantic-first design philosophy.
• Encourages ecosystem-wide adoption of named container queries for layout modules, design systems, and component libraries.
• Supports teardown-safe trait composition and export strategies in modular architectures.

Closing Thoughts

Expanding named container query support to range-based variants is a low-risk, high-impact enhancement. It strengthens Tailwind’s semantic backbone, empowers contributors, and unlocks expressive layout strategies that scale across teams and ecosystems.

Let’s make container queries as modular, semantic, and intuitive as the rest of Tailwind.

[wongjn]

This is already supported in Tailwind as per this Tailwind Play:

• Applies when container named 'foo' width is less than value:

  <div class="@max-xl/foo:bg-red-500"></div>

• Applies when container named 'foo' width is greater than or equal to value:

  <div class="@md/foo:bg-red-500"></div>

• Applies when container named 'foo' width is between value and max-value:

  <div class="@md/foo:@max-xl/foo:bg-red-500"></div>

[selcukcukur]

@wongjn I assumed it wasn't supported since it wasn't mentioned in the documentation—glad to hear it is!