Container

The wrapper around every page. Centered, capped at a max-width, padded responsive — the universal "page chrome" pattern. Without Container, every page in your app rewrites mx-auto max-w-7xl px-4 sm:px-6 lg:px-8 until somebody forgets a breakpoint.

import { Container } from '@dashforge/tw';

<Container size="lg" as="main">
  <h1>Page content lives here</h1>
</Container>

Quick Start

{/* Default — xl (1280px) max-width, responsive padding */}
<Container>
  <h1>App content</h1>
</Container>

{/* Documentation-friendly width */}
<Container size="lg">
  <article>Markdown article cap at 1024px</article>
</Container>

{/* Full-bleed (no max-width, padding still applies) */}
<Container size="fluid">
  Hero section that spans the viewport
</Container>

size defaults to 'xl' — comfortable for full app shells with a left nav + main + optional right rail.

Examples

Size scale — mapped to Tailwind breakpoints

import { Container, Box, Stack, Typography } from '@dashforge/tw';

<Stack gap={2}>
  <Container size="sm">
    <Box variant="outlined" p={3} rounded="md">
      <Typography variant="caption" color="muted">size="sm" — max-w-screen-sm (640px)</Typography>
    </Box>
  </Container>
  <Container size="md">
    <Box variant="outlined" p={3} rounded="md">
      <Typography variant="caption" color="muted">size="md" — max-w-screen-md (768px)</Typography>
    </Box>
  </Container>
  <Container size="lg">
    <Box variant="outlined" p={3} rounded="md">
      <Typography variant="caption" color="muted">size="lg" — max-w-screen-lg (1024px)</Typography>
    </Box>
  </Container>
</Stack>

<Container size="sm">  640px max</Container>
<Container size="md">  768px max</Container>
<Container size="lg">  1024px max</Container>
<Container size="xl">  1280px max — default</Container>
<Container size="2xl"> 1536px max</Container>
<Container size="fluid">no cap, edge to edge</Container>

Names match Tailwind's breakpoint vocabulary so the muscle memory carries: size="lg" ↔ max-w-screen-lg.

Padding control

{/* Default — responsive padding ramp */}
<Container>px-4 sm:px-6 lg:px-8 — the canonical ramp</Container>

{/* No padding — full bleed */}
<Container px={false}>
  <img src="hero.jpg" className="w-full" />
</Container>

{/* Custom vertical padding — Container doesn't expose `py`, use sx */}
<Container sx="py-12">section with vertical breathing room</Container>

The horizontal padding is opinionated: the px-4 sm:px-6 lg:px-8 ramp is what every well-spaced web app uses (it keeps edges from kissing the viewport on mobile and breathes more on larger screens). When you want full bleed at the page edges, pass px={false} — typical use case is a hero image or video that bleeds to the viewport edge.

centerContent — stack children centered

<Container centerContent size="md">
  <Typography variant="h1" align="center">Welcome back</Typography>
  <Typography variant="body1" color="muted">Sign in to continue</Typography>
  <Button color="primary">Continue with email</Button>
</Container>

centerContent turns the Container into a flex column with items-center. Useful for marketing pages, sign-in flows, "single artifact" layouts where the whole content stacks centered.

Polymorphic — as for semantic shell

{/* Primary content region of a page */}
<Container as="main" size="lg">
  <Outlet />
</Container>

{/* Named section in a longer layout */}
<Container as="section" size="lg" sx="py-16">
  <Typography variant="h2">Features</Typography>
</Container>

{/* Article shell */}
<Container as="article" size="md">
  <ArticleHeader />
  <ArticleBody />
</Container>

Use as="main" for the primary content region — gives you the semantic outline browsers and screen readers expect, plus the Container chrome in one component.

asChild — paint onto an existing element

import { Outlet } from 'react-router-dom';

<Container asChild size="xl">
  <main className="bg-neutral-50 dark:bg-neutral-950">
    <Outlet />
  </main>
</Container>

asChild merges Container's styles onto the child via Radix Slot — useful when the child already has semantic meaning AND its own classes you want preserved. tailwind-merge resolves conflicts (your child classes win where they collide with Container's).

Composition pattern — Container at root, Stack/Grid inside

<Container size="lg" as="main" sx="py-12">
  <Stack gap={8}>
    <Typography variant="h1">Workspace dashboard</Typography>

    <Grid container spacing={6}>
      <Grid xs={12} md={4}>
        <Box variant="outlined" rounded="xl" p={6}>Stats</Box>
      </Grid>
      <Grid xs={12} md={4}>
        <Box variant="outlined" rounded="xl" p={6}>Activity</Box>
      </Grid>
      <Grid xs={12} md={4}>
        <Box variant="outlined" rounded="xl" p={6}>Recent</Box>
      </Grid>
    </Grid>
  </Stack>
</Container>

Container handles the page chrome (centered, padded, capped width). Stack/Grid handle the actual layout of children. Three components, three concerns, zero overlap.

Nested Containers — fluid outer + capped inner

A common pattern for "full-bleed background, capped content":

<Container size="fluid" px={false} sx="bg-primary-50 py-16">
  <Container size="lg">
    <Typography variant="h2" align="center">Section title</Typography>
    <Typography variant="body1" align="center" color="muted">
      Background spans the viewport. Content stays capped at 1024px.
    </Typography>
  </Container>
</Container>

The outer Container provides the colored band edge-to-edge; the inner Container caps the text width for readability.

Theme defaults

Configure <Container> defaults application-wide through the theme.

import { patchTheme } from '@dashforge/tw-theme';

patchTheme({
  components: {
    Container: {
      defaults: { size: 'lg', px: 4, centerContent: false },
    },
  },
});

Configurable axes (ContainerVariantProps):

Non-visual axes (as, asChild, event handlers, ARIA) are not theme-configurable — per-instance choice.

Precedence chain (lowest → highest):

1. defaultVariants from the internal containerVariants recipe (size: 'xl', px: true).
2. theme.components.Container.defaults (application-wide).
3. Instance prop (<Container size="lg" />) — wins over theme.
4. sx — appended to the root and wins over conflicting classes via tailwind-merge.

TypeScript: theme.components.Container.defaults autocompletes to the three axes above.

Reactivity: useComponentDefaults('Container') subscribes to the theme store — patchTheme re-renders every mounted instance inheriting the changed axis.

API

Props

Slots & slotProps

<Container> has no slots. It renders a single DOM element (defaulting to <div>, overridable via as or asChild) — there is no anatomy to target separately.

The slotProps API pattern only exists on compound components with multiple visually distinct regions. Examples: <Menu>, <DataGrid>, <Card>.

For <Container>, use sx for any style override.

Variant catalogue

import { containerVariants } from '@dashforge/tw';
// containerVariants({ size: 'lg', px: true }) → className string

Notes

• Vertical padding is NOT exposed as a prop. Container is about the page chrome (horizontal axis). Use sx="py-12" when you need vertical breathing room — the choice usually varies per page/section, so a default would be wrong more often than right.
• fluid keeps mx-auto + w-full — that's a no-op for fluid (the width is already 100%), but consistent with the baseline so swapping size doesn't suddenly drop the centering.
• Default size is 'xl' — chosen for "full app with sidebar". For docs-only / marketing-only apps, set size="lg" at the page root explicitly.
• Composition over options: Container doesn't expose flex/grid props. Wrap your Stack/Grid inside. Single-responsibility per primitive.

When NOT to use

• For modal/dialog wrappers — those have their own positioning needs. Use ConfirmDialog or compose directly.
• For sidebar/nav constraints — those should be width-fixed, not max-width-fluid. Use Stack with sx="w-64" or similar.
• For per-section layout inside a page — Container is page-root. Inside, use Stack/Grid for the children's layout; only nest a second Container when you really need an inner cap (the fluid-outer + capped-inner pattern shown above).