CSS Container Queries: A First Look + Demo

~

~

# Container Queries?

Container Queries allow authors to style elements according to the size or appearance of a container. For size based container queries this is similar to a @media query, except that it will evaluate against the size of a parent container instead of the viewport.

For style based container queries you conditionally apply styles based on the calculated value of another CSS property.

~

# Quick Demo

Wanting to test Container Queries out I quickly threw a demo together using a classic card component. Here’s a recording that shows how this component behaves:

By default our component shows an image on top and a description below that. If enough space becomes available, they will be shown next to each other. Should even more space become available, then the image will grow even more.

~

# The Code

The markup for all those cards is the same and is pretty straightforward. Only extra thing I’ve added is an extra wrapper div .animalcard-wrapper so that our container queries will play nice when being used inside CSS Grid

<div class="animalcard-wrapper">
	<div class="animalcard">
		<div class="animalcard__image">
			…
		</div>
		<div class="animalcard__description">
			…
		</div>
	</div>
</div>

The default layout of our card uses CSS Grid to position the image and the description:

/* SMALL LAYOUT: Image stacked on top of Description */
.animalcard {
	display: grid;
	grid-template: "image" "description" / 1fr;
	gap: 1em;
	padding: 1em;
}

To be able to use Container Queries, we first need to create a Containment Context (Container Root) on the .animalcard-wrapper. We instruct the browser to keep track of the inline-size, which translates to the width, as we will be changing the layout of its children based on that dimension.

/* Container Queries: Create Container Root */
.animalcard-wrapper {
	container-type: inline-size;
}

You can also name your container query if you want:

/* Container Queries: Create Container Root (Named) */
.animalcard-wrapper {
	container-type: inline-size;
	container-name: animalwrapper;
}

Or, as a shorthand:

/* Container Queries: Create Container Root (Shorthand) */
.animalcard-wrapper {
	container: animalwrapper / inline-size;
}

With this Container Root in place, we can now add extra styles to apply when the Container Root reaches a certain width.

/* MEDIUM LAYOUT: Image next to Description (1fr each) */
@container (min-width: 30rem) {
	.animalcard {
		gap: 2em;
		padding: 2em;
		grid-template: "image description" / 1fr 1fr;
	}

	.animalcard__description {
		text-align: left;
	}
}

/* LARGE LAYOUT: Large Image next to Description */
@container (min-width: 70rem) {
	.animalcard {
		grid-template-columns: 2fr 1fr;
	}
}

By default it will be matched against the nearest parent that’s a container. If you want to explicitly target a different container, include its name when using @container:

/* MEDIUM LAYOUT: Image next to Description (1fr each) */
@container animalwrapper (min-width: 30rem) {
	…
}

If no parent container exists, the Small Viewport will be used.

~

# Final Demo

All together our demo finally becomes this:

See the Pen CSS Container Queries Demo by Bramus (@bramus) on CodePen.

To cater for browsers that don’t support Container Queries, a container queries polyfill is included.

~

# Browser Support

Container Queries has limited browser support, as seen in this Can I Use support table:

• Chromium 91.0.4459.0 with the #enable-container-queries flag enabled
• Safari Technology Preview 142

To stay up-to-date on the progress, and support for them in other browsers, you can follow these bugs:

• Blink/Chromium: Issue #1145970
• Gecko/Firefox: Issue #1744221
• WebKit/Safari: Issue #229659

~

~

# Updates

As the spec for this new CSS feature is still in flux, this post has received some updates over time in order to reflect the latest spec changes.

• Update 2022.03.31: The order for the arguments for the container shorthand got switched around.
• Update 2022.03.23: Safari Technology Preview ships with unflagged (size-based) Container Queries support! 🎉
• Update 2022.01.26: The function syntax for querying sizes — using size() — got dropped.
• Update 2021.11.26: To make the embedded demo work in browsers that don’t yet support Container Queries, it got extended with a Polyfill named container-queries-polyfill. Check out this post for more details on how to use it.
• Update 2021.06.11: To create a container you no longer need to set the contain property, but instead use the container property.
• Update 2021.05.02: Creating a Containment Context / Container Root also requires style containment.

~