Container

container centres a block of content and limits its width. Below the first breakpoint it takes the full width; from each breakpoint upwards its maximum width is that breakpoint’s width minus 100px, so there is always some space on both sides.

How container works

• Full width, centred. width: 100% and margin-inline: auto.
• Stepped maximum width. At each breakpoint, max-width becomes the breakpoint width minus 100px.
• Block padding. padding-top and padding-bottom use spacing key 4 (var(--nu-space-4)). There is no inline padding; add px-* for it.
• Display variants. container is a block; container flex and container grid make it a flex or grid container with the same widths.

Breakpoint	Minimum viewport width	Container max-width
(none)	Below 480px	100%
xs	480px	380px
sm	640px	540px
md	768px	668px
lg	1024px	924px
xl	1280px	1180px
2xl	1536px	1436px

The widths follow $breakpoints, which must be in px because 100px is subtracted from each.

Basic container

container px-4: centred, with a maximum width for the current breakpoint. Resize the window to see it step.

HTML

<div class="bg-alternate rounded">
  <div class="container px-4 bg-surface border rounded">
    container px-4: centred, with a maximum width for the current breakpoint. Resize the window to see it step.
  </div>
</div>

SCSS

.page {
  @include apply(container, px(4));
}

The preview canvas is narrower than the window, so the container fills it until the canvas is wider than the container’s maximum width at the current breakpoint. Breakpoints follow the viewport, not the parent.

Flex and grid containers

Combine container with flex or grid to get a centred layout container in one element. All the flex and grid modifiers work on it.

1

2

3

HTML

<div class="container grid cols-3 gap-4 px-4 bg-alternate rounded">
  <div class="p-3 bg-surface border rounded">1</div>
  <div class="p-3 bg-surface border rounded">2</div>
  <div class="p-3 bg-surface border rounded">3</div>
</div>

SCSS

.page-grid {
  @include apply(container(grid), cols(3), gap(4), px(4));
}

container flex and container grid need the flex and grid feature flags as well as container.

Full-bleed sections

A common page structure puts a full-width background on a section and a container inside it for the content.

Full-width background

The section spans the page; the container keeps the text at a readable width.

<section class="bg-brand-subtle rounded">
  <div class="container px-4">
    <h3 class="text-lg font-semibold">Full-width background</h3>
    <p class="text-muted mb-0">The section spans the page; the container keeps the text at a readable width.</p>
  </div>
</section>

Query containers

Container queries style an element by the width of its container instead of the viewport. Core has classes that turn an element into a query container, and mixins that write the queries.

Class	Declaration
container-inline-size	container-type: inline-size
container-size	container-type: size
container-main, container-sidebar, container-card, container-section	container-name with that name

container and the query container classes are separate: container sets widths and centring, container-inline-size makes an element queryable. An element can have both.

<aside class="container-inline-size container-sidebar">
  <div class="profile-card">...</div>
</aside>

.profile-card {
  @include apply(flex, col, gap(2));

  @include container-up(sm, sidebar) {
    @include apply(row, x-center);
  }
}

.profile-card {
  display: flex;
  flex-direction: column;
  gap: var(--nu-space-2);
}
.profile-card > * {
  --nu-flex-gap: var(--nu-space-2);
}
@container sidebar (min-width: 640px) {
  .profile-card {
    flex-direction: row;
    align-items: center;
  }
}

Mixin	Query
container-up($size, $name: null)	At least the breakpoint width (or a length)
container-down($size, $name: null)	Narrower than the breakpoint (0.02px below it)
container-between($lower, $upper, $name: null)	From the lower breakpoint up to just below the upper one
container-only($size, $name: null)	From the breakpoint up to just below the next one
container-query($size, $name: null)	At least the size, used as written
container-type($type: inline-size), container-name($name)	Make an element a query container

The query mixins accept breakpoint names or lengths. A unitless number that is not a breakpoint name raises an error; write a unit (container-up(400px)). Without a name, a query targets the nearest query container.

Responsive and state variants

The container classes have no responsive and no state variants: the stepped maximum width is already responsive. To use a container only from a breakpoint, apply the mixin in a media query:

.article {
  @include media-up(md) {
    @include container;
  }
}

SCSS

Mixin	Output
container($display: block)	The full container: display, width: 100%, margin-inline: auto, stepped max-width, block padding of key 4
container-base	width: 100% and margin-inline: auto only
container-padding($padding)	padding-top and padding-bottom: a spacing key gives its token, a value with a unit is used as written

@use "@nuvoui/core" as *;

.narrow {
  @include apply(container-base, max-width(48rem), px(4));
}
.section {
  @include container(flex);
  @include container-padding(8);
}

.narrow {
  width: 100%;
  margin-inline: auto;
  max-width: 48rem;
  padding-inline: var(--nu-space-4);
}

container-base with max-width gives a centred column of a single fixed width, for articles and forms.

container-padding() follows the spacing rules: container-padding(7) raises container-padding: 7 is not a configured key. Valid keys: 0, 1, 2, 3, 4, 5, 6, 8, 10, 12, 16, 20, 24, 32, 40, 48, 56, 64. Write a unit for a custom value (7px, 7rem).

Configuration

The container widths follow $breakpoints; the block padding uses spacing key 4, which must stay in $spacings. The container feature flag turns off .container, .container.flex and .container.grid; the container-queries flag turns off the query container classes. The mixins stay available.

@use "@nuvoui/core" with (
  $generate-utility-classes: true,
  $breakpoints: ("sm": 640px, "md": 768px, "lg": 1024px, "xl": 1280px)
);

The query container names (main, sidebar, card, section) are fixed in the package; container-name() accepts any name in SCSS.

Class reference

Generated from the compiled core build. Each container class also has max-width rules inside media queries, one per breakpoint, which are not listed.

Container (1 rules)

Selector	Declarations	Default value
.container	display: block width: 100% margin-inline: auto padding-top: var(--nu-space-4) padding-bottom: var(--nu-space-4)	block 100% auto 1rem 1rem

Query containers (6 rules)

Selector	Declarations	Default value
.container-inline-size	container-type: inline-size	inline-size
.container-size	container-type: size	size
.container-main	container-name: main	main
.container-sidebar	container-name: sidebar	sidebar
.container-card	container-name: card	card
.container-section	container-name: section	section

Accessibility and RTL

• Readable line length. A container limits how wide text runs on large screens. For long text, a narrower max-width such as 48rem keeps lines comfortable to read.
• Reflow. The container is full width below the first breakpoint, so content fits at 320 CSS pixels without horizontal scrolling (WCAG 1.4.10). Add inline padding with px-* so text does not touch the screen edge.
• RTL. Centring uses margin-inline: auto and the container has no inline padding of its own, so it is the same in both directions.

Note

Containers have no tokens. The block padding uses the spacing token --nu-space-4.