---
title: Grid
description: CSS grid container with configurable columns for equal or custom-width layouts.
icon: grip
---

import { ComponentPreview } from '/snippets/component-preview.mdx'

Grid is a CSS grid with configurable columns. Pass an integer for equal-width columns (1-12), or a list for custom widths like `[1, 3]` or `[1, "auto", 1]`. Children fill cells left-to-right, wrapping to new rows.

## Basic Usage

<ComponentPreview json={{"view":{"cssClass":"gap-4 grid-cols-3","type":"Grid","children":[{"cssClass":"bg-emerald-500 rounded-md h-10","type":"Div"},{"cssClass":"bg-emerald-500 rounded-md h-10","type":"Div"},{"cssClass":"bg-emerald-500 rounded-md h-10","type":"Div"},{"cssClass":"bg-emerald-500 rounded-md h-10","type":"Div"},{"cssClass":"bg-emerald-500 rounded-md h-10","type":"Div"},{"cssClass":"bg-emerald-500 rounded-md h-10","type":"Div"}]}}} playground="ZnJvbSBwcmVmYWJfdWkuY29tcG9uZW50cyBpbXBvcnQgKAogICAgRGl2LAogICAgR3JpZCwKKQoKd2l0aCBHcmlkKGNvbHVtbnM9MywgZ2FwPTQpOgogICAgZm9yIF8gaW4gcmFuZ2UoNik6CiAgICAgICAgRGl2KGNzc19jbGFzcz0iYmctZW1lcmFsZC01MDAgcm91bmRlZC1tZCBoLTEwIikK">
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import (
    Div,
    Grid,
)

with Grid(columns=3, gap=4):
    for _ in range(6):
        Div(css_class="bg-emerald-500 rounded-md h-10")
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "cssClass": "gap-4 grid-cols-3",
    "type": "Grid",
    "children": [
      {"cssClass": "bg-emerald-500 rounded-md h-10", "type": "Div"},
      {"cssClass": "bg-emerald-500 rounded-md h-10", "type": "Div"},
      {"cssClass": "bg-emerald-500 rounded-md h-10", "type": "Div"},
      {"cssClass": "bg-emerald-500 rounded-md h-10", "type": "Div"},
      {"cssClass": "bg-emerald-500 rounded-md h-10", "type": "Div"},
      {"cssClass": "bg-emerald-500 rounded-md h-10", "type": "Div"}
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

## Columns

The same set of children reflows as the column count changes.

<Tabs>
<Tab title="columns=2">
<ComponentPreview json={{"view":{"cssClass":"gap-4 grid-cols-2 p-3 border-3 border-dashed","type":"Grid","children":[{"cssClass":"bg-emerald-500 rounded-md h-10","type":"Div"},{"cssClass":"bg-emerald-500 rounded-md h-10","type":"Div"},{"cssClass":"bg-emerald-500 rounded-md h-10","type":"Div"},{"cssClass":"bg-emerald-500 rounded-md h-10","type":"Div"},{"cssClass":"bg-emerald-500 rounded-md h-10","type":"Div"},{"cssClass":"bg-emerald-500 rounded-md h-10","type":"Div"}]}}} playground="ZnJvbSBwcmVmYWJfdWkuY29tcG9uZW50cyBpbXBvcnQgRGl2LCBHcmlkCgp3aXRoIEdyaWQoY29sdW1ucz0yLCBnYXA9NCwgY3NzX2NsYXNzPSJwLTMgYm9yZGVyLTMgYm9yZGVyLWRhc2hlZCIpOgogICAgZm9yIF8gaW4gcmFuZ2UoNik6CiAgICAgICAgRGl2KGNzc19jbGFzcz0iYmctZW1lcmFsZC01MDAgcm91bmRlZC1tZCBoLTEwIikK">
<CodeGroup>
```python Python highlight={3} icon="python"
from prefab_ui.components import Div, Grid

with Grid(columns=2, gap=4, css_class="p-3 border-3 border-dashed"):
    for _ in range(6):
        Div(css_class="bg-emerald-500 rounded-md h-10")
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "cssClass": "gap-4 grid-cols-2 p-3 border-3 border-dashed",
    "type": "Grid",
    "children": [
      {"cssClass": "bg-emerald-500 rounded-md h-10", "type": "Div"},
      {"cssClass": "bg-emerald-500 rounded-md h-10", "type": "Div"},
      {"cssClass": "bg-emerald-500 rounded-md h-10", "type": "Div"},
      {"cssClass": "bg-emerald-500 rounded-md h-10", "type": "Div"},
      {"cssClass": "bg-emerald-500 rounded-md h-10", "type": "Div"},
      {"cssClass": "bg-emerald-500 rounded-md h-10", "type": "Div"}
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>
</Tab>
<Tab title="columns=3">
<ComponentPreview json={{"view":{"cssClass":"gap-4 grid-cols-3 p-3 border-3 border-dashed","type":"Grid","children":[{"cssClass":"bg-emerald-500 rounded-md h-10","type":"Div"},{"cssClass":"bg-emerald-500 rounded-md h-10","type":"Div"},{"cssClass":"bg-emerald-500 rounded-md h-10","type":"Div"},{"cssClass":"bg-emerald-500 rounded-md h-10","type":"Div"},{"cssClass":"bg-emerald-500 rounded-md h-10","type":"Div"},{"cssClass":"bg-emerald-500 rounded-md h-10","type":"Div"}]}}} playground="ZnJvbSBwcmVmYWJfdWkuY29tcG9uZW50cyBpbXBvcnQgRGl2LCBHcmlkCgp3aXRoIEdyaWQoY29sdW1ucz0zLCBnYXA9NCwgY3NzX2NsYXNzPSJwLTMgYm9yZGVyLTMgYm9yZGVyLWRhc2hlZCIpOgogICAgZm9yIF8gaW4gcmFuZ2UoNik6CiAgICAgICAgRGl2KGNzc19jbGFzcz0iYmctZW1lcmFsZC01MDAgcm91bmRlZC1tZCBoLTEwIikK">
<CodeGroup>
```python Python highlight={3} icon="python"
from prefab_ui.components import Div, Grid

with Grid(columns=3, gap=4, css_class="p-3 border-3 border-dashed"):
    for _ in range(6):
        Div(css_class="bg-emerald-500 rounded-md h-10")
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "cssClass": "gap-4 grid-cols-3 p-3 border-3 border-dashed",
    "type": "Grid",
    "children": [
      {"cssClass": "bg-emerald-500 rounded-md h-10", "type": "Div"},
      {"cssClass": "bg-emerald-500 rounded-md h-10", "type": "Div"},
      {"cssClass": "bg-emerald-500 rounded-md h-10", "type": "Div"},
      {"cssClass": "bg-emerald-500 rounded-md h-10", "type": "Div"},
      {"cssClass": "bg-emerald-500 rounded-md h-10", "type": "Div"},
      {"cssClass": "bg-emerald-500 rounded-md h-10", "type": "Div"}
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>
</Tab>
<Tab title="columns=4">
<ComponentPreview json={{"view":{"cssClass":"gap-4 grid-cols-4 p-3 border-3 border-dashed","type":"Grid","children":[{"cssClass":"bg-emerald-500 rounded-md h-10","type":"Div"},{"cssClass":"bg-emerald-500 rounded-md h-10","type":"Div"},{"cssClass":"bg-emerald-500 rounded-md h-10","type":"Div"},{"cssClass":"bg-emerald-500 rounded-md h-10","type":"Div"},{"cssClass":"bg-emerald-500 rounded-md h-10","type":"Div"},{"cssClass":"bg-emerald-500 rounded-md h-10","type":"Div"}]}}} playground="ZnJvbSBwcmVmYWJfdWkuY29tcG9uZW50cyBpbXBvcnQgRGl2LCBHcmlkCgp3aXRoIEdyaWQoY29sdW1ucz00LCBnYXA9NCwgY3NzX2NsYXNzPSJwLTMgYm9yZGVyLTMgYm9yZGVyLWRhc2hlZCIpOgogICAgZm9yIF8gaW4gcmFuZ2UoNik6CiAgICAgICAgRGl2KGNzc19jbGFzcz0iYmctZW1lcmFsZC01MDAgcm91bmRlZC1tZCBoLTEwIikK">
<CodeGroup>
```python Python highlight={3} icon="python"
from prefab_ui.components import Div, Grid

with Grid(columns=4, gap=4, css_class="p-3 border-3 border-dashed"):
    for _ in range(6):
        Div(css_class="bg-emerald-500 rounded-md h-10")
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "cssClass": "gap-4 grid-cols-4 p-3 border-3 border-dashed",
    "type": "Grid",
    "children": [
      {"cssClass": "bg-emerald-500 rounded-md h-10", "type": "Div"},
      {"cssClass": "bg-emerald-500 rounded-md h-10", "type": "Div"},
      {"cssClass": "bg-emerald-500 rounded-md h-10", "type": "Div"},
      {"cssClass": "bg-emerald-500 rounded-md h-10", "type": "Div"},
      {"cssClass": "bg-emerald-500 rounded-md h-10", "type": "Div"},
      {"cssClass": "bg-emerald-500 rounded-md h-10", "type": "Div"}
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>
</Tab>
</Tabs>

## Custom Column Widths

Pass a list to `columns` for unequal-width columns. Integers become fractional units (`1` → `1fr`, `2` → `2fr`) and strings pass through as CSS values (`"auto"`, `"200px"`).

<ComponentPreview json={{"view":{"cssClass":"gap-6 p-3 border-3 border-dashed","type":"Grid","columnTemplate":"1fr 3fr","children":[{"cssClass":"p-3 border-3 border-dashed","type":"Column","children":[{"content":"Sidebar","type":"H3"},{"content":"Navigation or filters.","type":"P"}]},{"cssClass":"p-3 border-3 border-dashed","type":"Column","children":[{"content":"Main Content","type":"H3"},{"content":"The sidebar gets 1/4 of the space; main content gets 3/4.","type":"P"}]}]}}} playground=" ">
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import Column, Grid, H3, P

with Grid(columns=[1, 3], gap=6, css_class="p-3 border-3 border-dashed"):
    with Column(css_class="p-3 border-3 border-dashed"):
        H3("Sidebar")
        P("Navigation or filters.")
    with Column(css_class="p-3 border-3 border-dashed"):
        H3("Main Content")
        P("The sidebar gets 1/4 of the space; main content gets 3/4.")
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "cssClass": "gap-6 p-3 border-3 border-dashed",
    "type": "Grid",
    "columnTemplate": "1fr 3fr",
    "children": [
      {
        "cssClass": "p-3 border-3 border-dashed",
        "type": "Column",
        "children": [
          {"content": "Sidebar", "type": "H3"},
          {"content": "Navigation or filters.", "type": "P"}
        ]
      },
      {
        "cssClass": "p-3 border-3 border-dashed",
        "type": "Column",
        "children": [
          {"content": "Main Content", "type": "H3"},
          {
            "content": "The sidebar gets 1/4 of the space; main content gets 3/4.",
            "type": "P"
          }
        ]
      }
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

The `"auto"` keyword sizes a column to its content, which works well for separators or fixed-width controls between fluid areas.

<ComponentPreview json={{"view":{"cssClass":"gap-6 p-3 border-3 border-dashed","type":"Grid","columnTemplate":"1fr auto 1fr","children":[{"cssClass":"p-3 border-3 border-dashed","type":"Column","children":[{"content":"Panel A","type":"H3"},{"content":"Left side content.","type":"P"}]},{"type":"Separator","orientation":"vertical"},{"cssClass":"p-3 border-3 border-dashed","type":"Column","children":[{"content":"Panel B","type":"H3"},{"content":"Right side content.","type":"P"}]}]}}} playground=" ">
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import Column, Grid, H3, P, Separator

with Grid(columns=[1, "auto", 1], gap=6, css_class="p-3 border-3 border-dashed"):
    with Column(css_class="p-3 border-3 border-dashed"):
        H3("Panel A")
        P("Left side content.")
    Separator(orientation="vertical")
    with Column(css_class="p-3 border-3 border-dashed"):
        H3("Panel B")
        P("Right side content.")
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "cssClass": "gap-6 p-3 border-3 border-dashed",
    "type": "Grid",
    "columnTemplate": "1fr auto 1fr",
    "children": [
      {
        "cssClass": "p-3 border-3 border-dashed",
        "type": "Column",
        "children": [
          {"content": "Panel A", "type": "H3"},
          {"content": "Left side content.", "type": "P"}
        ]
      },
      {"type": "Separator", "orientation": "vertical"},
      {
        "cssClass": "p-3 border-3 border-dashed",
        "type": "Column",
        "children": [
          {"content": "Panel B", "type": "H3"},
          {"content": "Right side content.", "type": "P"}
        ]
      }
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

## Auto-fill Columns

Set `min_column_width` instead of `columns` to let CSS Grid automatically fit as many columns as possible, each at least the given width. Drag the handle to see the grid reflow.

<ComponentPreview resizable json={{"view":{"cssClass":"gap-4","type":"Grid","minColumnWidth":"10rem","children":[{"cssClass":"bg-emerald-500 rounded-md h-10","type":"Div"},{"cssClass":"bg-emerald-500 rounded-md h-10","type":"Div"},{"cssClass":"bg-emerald-500 rounded-md h-10","type":"Div"},{"cssClass":"bg-emerald-500 rounded-md h-10","type":"Div"},{"cssClass":"bg-emerald-500 rounded-md h-10","type":"Div"},{"cssClass":"bg-emerald-500 rounded-md h-10","type":"Div"}]}}} playground="ZnJvbSBwcmVmYWJfdWkuY29tcG9uZW50cyBpbXBvcnQgRGl2LCBHcmlkCgp3aXRoIEdyaWQobWluX2NvbHVtbl93aWR0aD0iMTByZW0iLCBnYXA9NCk6CiAgICBmb3IgXyBpbiByYW5nZSg2KToKICAgICAgICBEaXYoY3NzX2NsYXNzPSJiZy1lbWVyYWxkLTUwMCByb3VuZGVkLW1kIGgtMTAiKQo=">
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import Div, Grid

with Grid(min_column_width="10rem", gap=4):
    for _ in range(6):
        Div(css_class="bg-emerald-500 rounded-md h-10")
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "cssClass": "gap-4",
    "type": "Grid",
    "minColumnWidth": "10rem",
    "children": [
      {"cssClass": "bg-emerald-500 rounded-md h-10", "type": "Div"},
      {"cssClass": "bg-emerald-500 rounded-md h-10", "type": "Div"},
      {"cssClass": "bg-emerald-500 rounded-md h-10", "type": "Div"},
      {"cssClass": "bg-emerald-500 rounded-md h-10", "type": "Div"},
      {"cssClass": "bg-emerald-500 rounded-md h-10", "type": "Div"},
      {"cssClass": "bg-emerald-500 rounded-md h-10", "type": "Div"}
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

## Responsive Columns

Pass a dictionary of breakpoints to `columns` for precise control at specific viewport widths. The `default` key sets the base, and Tailwind breakpoints (`sm`, `md`, `lg`, `xl`, `2xl`) override it progressively.

```python
Grid(columns={"default": 1, "md": 2, "lg": 3})
```

See [Responsive Layout Props](/css#responsive-layout-props) for responsive `gap`, `css_class`, and the `Responsive` helper.

## Nested Content

Grids nest naturally with other containers:

<ComponentPreview json={{"view":{"cssClass":"gap-6 grid-cols-2 p-3 border-3 border-dashed","type":"Grid","children":[{"cssClass":"p-3 border-3 border-dashed","type":"Column","children":[{"content":"Left Panel","type":"H3"},{"content":"Primary content goes here.","type":"P"}]},{"cssClass":"p-3 border-3 border-dashed","type":"Column","children":[{"content":"Right Panel","type":"H3"},{"content":"Secondary content goes here.","type":"P"}]}]}}} playground=" ">
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import (
    Column,
    Grid,
    H3,
    P,
)

with Grid(columns=2, gap=6, css_class="p-3 border-3 border-dashed"):
    with Column(css_class="p-3 border-3 border-dashed"):
        H3("Left Panel")
        P("Primary content goes here.")
    with Column(css_class="p-3 border-3 border-dashed"):
        H3("Right Panel")
        P("Secondary content goes here.")
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "cssClass": "gap-6 grid-cols-2 p-3 border-3 border-dashed",
    "type": "Grid",
    "children": [
      {
        "cssClass": "p-3 border-3 border-dashed",
        "type": "Column",
        "children": [
          {"content": "Left Panel", "type": "H3"},
          {"content": "Primary content goes here.", "type": "P"}
        ]
      },
      {
        "cssClass": "p-3 border-3 border-dashed",
        "type": "Column",
        "children": [
          {"content": "Right Panel", "type": "H3"},
          {"content": "Secondary content goes here.", "type": "P"}
        ]
      }
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

## API Reference

<Card icon="code" title="Grid Parameters">
<ParamField body="columns" type="int | list | dict | Responsive" default="3">
  Number of grid columns (1-12), or a list of column widths. Can be passed as a positional argument. In a list, integers become fractional units (`1` → `1fr`) and strings pass through (`"auto"`, `"200px"`). Pass a dict or `Responsive()` for breakpoint-aware column counts. Mutually exclusive with `min_column_width`.
</ParamField>

<ParamField body="min_column_width" type="str | None" default="None">
  Minimum column width for auto-fill responsive grids (e.g. `"16rem"`). CSS Grid fits as many columns as possible at this minimum width. Mutually exclusive with `columns`.
</ParamField>

<ParamField body="gap" type="int | tuple | Responsive | None" default="None">
  Gap between children. An int maps to `gap-{n}`. A tuple `(x, y)` sets per-axis gaps; use `None` to skip an axis. A `Responsive()` sets different gaps at different breakpoints.
</ParamField>

<ParamField body="align" type="str | None" default="None">
  Cross-axis alignment: `"start"`, `"center"`, `"end"`, `"stretch"`, `"baseline"`.
</ParamField>

<ParamField body="justify" type="str | None" default="None">
  Main-axis distribution: `"start"`, `"center"`, `"end"`, `"between"`, `"around"`, `"evenly"`, `"stretch"`.
</ParamField>

<ParamField body="css_class" type="str | Responsive | None" default="None">
  Additional Tailwind CSS classes. A `Responsive()` compiles breakpoint-prefixed classes.
</ParamField>
</Card>

## Protocol Reference

```json Grid
{
  "type": "Grid",
  "children?": "[Component]",
  "let?": "object",
  "columns?": "number | Action[] | object",
  "columnTemplate?": "string",
  "minColumnWidth?": "string",
  "gap?": "number | Action[]",
  "align?": "start | center | end | stretch | baseline",
  "justify?": "start | center | end | between | around | evenly | stretch",
  "cssClass?": "string"
}
```

For the complete protocol schema, see [Grid](/protocol/grid).
