container-name

The CSS container-name property is used to register an element as a container that applies styles to other elements based on the container’s size and styles.

.parent {
  container-name: cards;
  container-type: inline-size;
}

@container cards (width > 800px) {
  .child {
    width: 50cqi;
  }
}

In this example, we have registered a new container called cards out of elements with a class of .parent that looks at the element’s inline-size — i.e., width in a standard horizontal writing mode — and changes the .child element’s size when the container is greater than 800px when used with @container to query that specific container.

Syntax

container-name: none | <custom-ident>+;

• Initial value: none
• Applies to: All elements
• Inherited: No
• Percentages: N/A
• Computed value: none or an ordered list of identifiers
• Canonical order: Per grammar
• Animation: Not animatable

Values

The container-name property accepts one value or multiple values separated by a single space.

/* No container */
container-name: none;

/* Single value */
container-name: wrapper;

/* Two values */
container-name: wrapper hero-banner;

/* Global Values */
container-name: inherit;
container-name: initial;
container-name: revert;
container-name: revert-layer;
container-name: unset;

• none: The element does not have a container name. This is true by default, so you will likely never use this value, as its purpose is purely to set the property’s default behavior.
• <custom-ident>: This is the name of the container, which can be anything, except for words that are reserved for other functions, including default, none, at, no, and or. Note that the names are not wrapped in quotes.

It’s used with the container-type property

That’s right, make sure to use container-name along with container-type to properly register a specific container that can be queried by its size. The name identifies it and the type creates a containment context.

.parent {
  container-name: cards;
  container-type: inline-size;
}

That said…

Naming containers is optional

An unnamed container will match any @container query that does not explicitly target a specific container name.

.parent {
  container-type: inline-size;
}

/* Matches any container, named or unnamed */
@container (width < 600px) {
  .child {
    width: 100cqi;
  }
}

It’s included in the container shorthand property

If you would rather not write out both container-name and container-type as separate declarations (and who would blame you?), then you can use the container shorthand property instead, which combines the two properties into a single declaration, separated by a forward slash (/).

.parent {
  container: cards / inline-size;

  /* Equivalent to: */
  container-name: cards;
  container-type: inline-size;
}

Working with multiple container names

Earlier, we mentioned how it’s possible to set multiple container names on an element as long as they are separated by spaces:

.parent {
  container: layout hero-banner / inline-size;

  /* Or */
  container-name: layout hero-banner;
  container-type: inline-size;
}

When we do that, we can potentially query the container when multiple conditions are true:

@container layout (width < 600px) {
  article {
    flex-direction: column;
  }
}

@container hero-banner (width > 400px) {
  article h2 {
    font-size: 2rem;
  }
}

Specification

The container-name property is defined in the CSS Containment Module Level 3 specification, which is currently in Editor’s Draft status at the time of this writing.

Browser support

More on Container Queries

Related