# Layout Components

Layout components arrange the page. They define the visual skeleton — full-width heroes, centered containers, flex and grid tracks, cards, sidebars, and modals — and host other components as `children`. Every layout component accepts the shared `props` bag (rendered as HTML attributes such as `className`), plus `responsive`, `visibility`, and `i18n` modules. Container-like components additionally accept `children`.

```yaml
components:
  - type: hero
    content: Ship internal tools from config
    props: { className: 'bg-primary text-white py-24' }
  - type: container
    props: { className: 'max-w-4xl mx-auto px-6' }
    children:
      - type: grid
        props: { className: 'grid-cols-3 gap-6' }
        children:
          - { type: card, children: [{ type: text, content: 'Fast' }] }
```

## `hero`

A full-width banner section, typically the first block on a landing page. Renders `content` as its headline and accepts `children` for CTAs and supporting content.

| Property       | Description                                                                     |
| -------------- | ------------------------------------------------------------------------------- |
| `content`      | Headline text (supports `$record.*`, `$vars.*`, `$t:key` substitution).         |
| `children`     | Nested components rendered inside the hero (subtitles, buttons, media).         |
| `props`        | HTML attributes — typically `className` for background, padding, and alignment. |
| `interactions` | Click/hover/entrance behaviors (e.g. an entrance animation on load).            |
| `responsive`   | Per-breakpoint overrides.                                                       |
| `visibility`   | Conditional display based on auth state.                                        |

## `container`

A generic block-level wrapper. Use it to constrain width, apply padding, and group children.

| Property   | Description                                                                    |
| ---------- | ------------------------------------------------------------------------------ |
| `element`  | HTML element to render. Defaults to `div` (e.g. `section`, `main`, `article`). |
| `children` | Nested component definitions.                                                  |
| `content`  | Optional inline content rendered when no `children` are present.               |
| `props`    | HTML attributes (e.g. `className`).                                            |

## `flex`

A flexbox container. Lay out children in a row or column with gap, alignment, and wrapping controlled via Tailwind classes in `props.className`.

| Property     | Description                                                                                       |
| ------------ | ------------------------------------------------------------------------------------------------- |
| `children`   | Nested components arranged along the flex axis.                                                   |
| `props`      | HTML attributes — set `className` to `flex flex-row`/`flex-col`, `gap-*`, `items-*`, `justify-*`. |
| `responsive` | Per-breakpoint direction/alignment overrides.                                                     |

## `grid`

A CSS grid container with fixed column tracks. Children flow into the grid cells.

| Property   | Description                                                                      |
| ---------- | -------------------------------------------------------------------------------- |
| `children` | Nested components placed into grid cells.                                        |
| `props`    | HTML attributes — set `className` to `grid grid-cols-*`, `gap-*`, `auto-rows-*`. |

## `responsiveGrid`

A grid whose column count adapts per breakpoint. Prefer this over `grid` when you want declarative responsive columns without hand-writing breakpoint classes.

| Property     | Description                                            |
| ------------ | ------------------------------------------------------ |
| `children`   | Nested components placed into the responsive grid.     |
| `responsive` | Per-breakpoint column counts (mobile, sm, md, lg, xl). |
| `props`      | HTML attributes (e.g. `gap-*`).                        |

## `card`

A bordered, padded surface for grouping related content. Commonly used in grids and galleries.

| Property       | Description                                                       |
| -------------- | ----------------------------------------------------------------- |
| `children`     | Nested components rendered inside the card body.                  |
| `content`      | Optional inline content when no `children` are provided.          |
| `props`        | HTML attributes — `className` for elevation, radius, and padding. |
| `interactions` | Click/hover effects (e.g. hover elevation, navigate on click).    |

## `sidebar`

A vertical navigation panel, typically paired with a `container` main region to form an app-shell layout. Can be statically composed from `children` or data-bound through the page `layout.sidebar` config (see [Pages Overview → Layouts & Sidebars](/en/docs/pages-overview#layouts--sidebars)).

| Property     | Description                                                                  |
| ------------ | ---------------------------------------------------------------------------- |
| `children`   | Navigation items and sections rendered as a vertical menu.                   |
| `props`      | HTML attributes — `className` for width and positioning (fixed-width panel). |
| `visibility` | Conditional display (e.g. hide for unauthenticated users).                   |

## `modal`

A dialog overlay opened by an interaction trigger. The `modal` layout component holds the dialog body; open it via a button's `interactions.onClick` with `modalId`. (For confirmation-style overlays, see [`dialog`/`alert-dialog`](/en/docs/overlay-components).)

| Property   | Description                                                    |
| ---------- | -------------------------------------------------------------- |
| `id`       | Identifier targeted by an opening trigger (`onClick.modalId`). |
| `children` | Nested components rendered inside the modal panel.             |
| `props`    | HTML attributes (e.g. `className` for panel sizing).           |

Clicking the backdrop or pressing Escape closes the modal; focus is trapped within the modal while open.

## `tab-panel`

A single panel within a `tabs` container. Each panel has a trigger label and its own content/children. See [`tabs`](/en/docs/navigation-components#tabs) for the container.

| Property   | Description                                                                |
| ---------- | -------------------------------------------------------------------------- |
| `label`    | Text shown on the tab trigger button.                                      |
| `content`  | Inline text content of the panel (omit when the panel renders `children`). |
| `children` | Nested components rendered inside the panel.                               |

## `divider`

A horizontal rule separating sections of content.

| Property      | Description                                     |
| ------------- | ----------------------------------------------- |
| `props.style` | Line style: `solid`, `dashed`, or `dotted`.     |
| `props.label` | Centered text rendered within the divider line. |
| `props`       | Additional HTML attributes (e.g. `className`).  |

## `spacer`

Vertical whitespace between blocks.

| Property     | Description                                    |
| ------------ | ---------------------------------------------- |
| `props.size` | Spacing preset: `sm`, `md`, `lg`, or `xl`.     |
| `props`      | Additional HTML attributes (e.g. `className`). |

```yaml
components:
  - { type: text, tag: h2, content: 'Section A' }
  - { type: spacer, props: { size: lg } }
  - { type: divider, props: { style: dashed, label: 'or' } }
  - { type: text, tag: h2, content: 'Section B' }
```

## Related Pages

- [Pages Overview](/en/docs/pages-overview) — page structure, routing, and the component model.
- [Content Components](/en/docs/content-components) — text, code, callouts, accordions.
- [Navigation Components](/en/docs/navigation-components) — tabs, breadcrumbs, menus.
- [Overlay Components](/en/docs/overlay-components) — dialogs, drawers, popovers.
- [Theme](/en/docs/theme) — design tokens consumed by `className` styling.