include-container

A tiny Sass helper that ports the beloved include-media API to Container Queries.

Same shorthand syntax: '>=md', '<lg', 'height >= 40ch'
No media-query fallback (by design) — no global layout surprises
Optional @supports guard for container-type (enabled by default)
Works with named containers (container-name) or unnamed ones
Ships with a sensible default breakpoints map and unit intervals (including ch)

Author: @PaulLVG
License: MIT

Credits & Acknowledgements

This project is a respectful fork and adaptation of the wonderful include-media library originally created by:

Eduardo Boucas – @eduardoboucas
Kitty Giraudel – @KittyGiraudel

All credits go to them for their elegant Sass design and documentation style.
This project merely extends their ideas to CSS Container Queries.

Maintained by @PaulLVG

Installation

npm i -D include-container
# or
pnpm add -D include-container

Import it in your Sass folder:

// Override defaults BEFORE importing (optional)
$ic-breakpoints: (
  'xxs': 320px,
  'xs':  480px,
  'sm':  640px,
  'md':  768px,
  'lg':  1024px,
  'xl':  1280px,
  'xxl': 1536px
);

// Optionally disable @supports guard (not recommended)
$ic-guard-supports: true;

// Now import the library
@use "include-container";

If you vend this file directly (not via npm), just @use "include-container"; with the file in your load path.

Getting started

Examples

// Inline-size by default
@include container('>=md') {
  .card { display: grid; gap: 1rem; }
}

// Height-based container query
@include container('height >= 40ch') {
  .teaser { display: block; }
}

// Named container
@include container('>=lg', $name: 'layout') {
  .sidebar { position: sticky; top: 1rem; }
}

// Combine conditions (min AND max)
@include container('>=sm', '<=lg') {
  .grid { grid-template-columns: repeat(2, 1fr); }
}

// Custom tweakpoint in scope:
@include container-context(($tall: 70ch)) {
  @include container('height>=tall') {
    .hero { align-items: center; }
  }
}

Backwards-compatible alias

Just in case your project already includes a mixin called “container”, this syntax also works:

@include include-container('>sm') { /* ... */ }

Browser support

Relies on CSS Container Queries, supported by all modern browsers:

Chrome ≥ 105
Edge ≥ 105
Firefox ≥ 109
Safari ≥ 16.4

Use the @supports (container-type: inline-size) guard to prevent errors on older engines.

Why another library?

include-container brings the same developer experience as include-media — but for Container Queries. No reinvented syntax, no JavaScript runtime, just pure Sass sugar syntax for modern responsive components.

Why no media-query fallback?

Container Queries are contextual. Falling back to viewport-based media queries can break layouts when a component is designed to react to its container (e.g., a small card in a wide desktop page).
This library does not emit any media fallback by design. It optionally wraps output with:

@supports (container-type: inline-size) { ... }

So unsupported browsers just don’t apply those rules (safer default).

API

`@include container($conditions..., $name: null, $type: null, $supports: null)`

$conditions…: one or more shorthand expressions (strings)
- '>=md', '<lg'
- 'height >= 40ch', 'block-size < 60ch'
$name: optional container name (must match container-name in your CSS)
$type: if set to 'size', the @supports guard uses (container-type: size).
- When omitted, inline-size is assumed.
$supports: whether to wrap output in a @supports rule. Defaults to $ic-guard-supports (true).

The mixin supports multiple conditions by nesting @container rules (equivalent to logical AND).

Configuration

Breakpoints

Default map (override before @use):

$ic-breakpoints: (
  'xxs': 320px,
  'xs':  480px,
  'sm':  640px,
  'md':  768px,
  'lg':  1024px,
  'xl':  1280px,
  'xxl': 1536px
);

You can refer to named breakpoints in conditions, e.g. '>=md', '<xl'.

Unit intervals

For exclusive ranges (> / <), include-container adjusts the numeric value with a small unit interval (like include-media). Default:

$ic-unit-intervals: (
  'px': 1,
  'em': 0.01,
  'rem': 0.1, // common when :root font-size is 62.5%
  'ch': 0.1,  // convenient for typographic widths
  '':  0
);

So '> 40ch' becomes (min-width: 40.1ch) and '< 60ch' becomes (max-width: 59.9ch).

Supports guard

Enabled by default for safety:

$ic-guard-supports: true;

If $type: 'size', guard uses (container-type: size).
Otherwise it uses (container-type: inline-size).

Set $ic-guard-supports: false only if you’re certain about your target browsers.

Using `ch` units (typographic containers)

ch is roughly the width of the “0” glyph in the current font. It’s great for readable text widths. Common guidelines:

Long-form text line length: 55–75ch sweet spot
Narrow columns / sidebars: 35–50ch
Hero text blocks: 60–75ch

Examples:

// Make a card layout once the container is at least a comfortable text width
@include container('>= 60ch') {
  .article-card { display: grid; grid-template-columns: 2fr 1fr; gap: 1.25rem; }
}

// Collapse to a single column below 45ch
@include container('< 45ch') {
  .article-card { grid-template-columns: 1fr; }
}

Remember: the parent must establish a container context, e.g.:

.content-area {
  container-type: inline-size;          // or: size
  container-name: layout;
}

License

MIT © @PaulLVG

This site is open source. Improve this page.