# Layout - Textual (official guide)

## Metadata

| Field | Value |
|---|---|
| Institute | Molodetz Institute — Research & Retrieval Division |
| Subject | tui-framework-design |
| Document type | Source Dossier |
| Tier | 1 |
| Source title | Layout - Textual |
| Source URL | https://textual.textualize.io/guide/layout/ |
| Source publisher / author | Textualize |
| Source type | vendor docs |
| Source date (published) | Unknown — not stated |
| Date researched | 2026-10-10 |
| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
| Research method | direct page fetch |
| Confidence | High |
| Status | Active |

## Summary

Textual's official layout guide: containers arrange children with `vertical`, `horizontal`, or `grid` layouts; sizes use cells, `fr` fractions, `%`, or `auto`; `dock` pins widgets to an edge outside the flow; named `layers` control paint order; `offset` shifts widgets visually. Yield order decides paint order unless layers override it.

## Key findings

- Screen defaults to `vertical` layout; children stack top to bottom (vertical) or left to right (horizontal).
- `fr` units split free space proportionally (`height: 1fr` on three children = equal thirds); `%` sizes against the parent; `auto` sizes to content.
- Widgets expand to the parent's width by default but not its height (explicit `height: 100%` needed).
- `overflow-x/y: auto` adds scrollbars when children exceed the container; wheel/trackpad/keyboard scroll the focused container.
- `dock: top|right|bottom|left` removes a widget from flow and pins it to an edge; docked widgets never scroll (headers, footers, sidebars).
- Overlapping docked widgets paint in yield order: later yield = on top.
- `layers` on a container declares space-separated layer names (leftmost = lowest); descendants take `layer: <name>`; layer order beats yield order.
- Grid supports `grid-size`, `grid-columns`/`grid-rows` (incl. `auto`, `fr`, `%`), `row-span`/`column-span`, and `grid-gutter`.

## Pros / strengths

- Authoritative with a worked example per concept; the vocabulary (flow, dock, layers, offset) is small yet covers headers, sidebars, grids, and overlapping popups.

## Cons / limitations / caveats

- CSS-syntax specific; no algorithm internals (those live in Textual's `_compositor.py` source, not this guide).
- Utility containers (Vertical/Horizontal/Grid) are thin wrappers; the ideas matter more than the classes.

## Relevance to tai

- Supplies the exact layout vocabulary tai's Panel needs: rows/cols flow containers, `fr` + `%` + auto sizing, dock edges, named layers with z, offsets — matching the requested rows/cols/percentage/alignment feature set one for one.
- tai will express the same concepts as constructor kwargs and methods (no CSS parser): `Rows`, `Cols`, `dock="left"`, `layer="dialog"`, `offset=(x, y)`.

## Changelog

| Date | Change |
|---|---|
| 2026-10-10 | Initial dossier created. |