Grid

In plain words

Arranges things in rows and columns, like tiles on a wall.

Lays out children in a grid. With columns=3 the columns are equal, and max_width fits as many as possible. With track lists (columns=[200, "1fr", "auto"]) it works like a CSS grid, and pz.cell(child, column=, row=, column_span=, row_span=) places a child explicitly.

pz.grid · Category: Layout · Full reference →

Preview

Code

box = lambda text, w=90, h=44: pz.container(ui.label(text), center=True, width=w, height=h, bg=pz.theme.current().element, radius=6)
pz.container(pz.grid([box(str(i), w="fill") for i in range(1, 9)], columns=4, spacing=8), width=440)

New

This component was added recently. Tell us how it works for you in the issue tracker.

When to use

• For galleries, dashboards and page layouts with a header, sidebar and content.

Usage

import pyzed as pz
from pyzed import ui

box = lambda text, w=90, h=44: pz.container(ui.label(text), center=True, width=w, height=h, bg=pz.theme.current().element, radius=6)
pz.container(pz.grid([box(str(i), w="fill") for i in range(1, 9)], columns=4, spacing=8), width=440)

Variants

About these captures

Each capture is recorded by pyzed itself, off-screen at 2x, in One Dark or One Light to match this site’s theme, and cropped to the component so it shows at its real size. The pointer hovers, presses or types into it; a component that does not react to the pointer cycles through a few themes. With reduced motion you see the first frame. Open Code under a capture to see the snippet that draws it; free names such as on_save stand for your own callbacks.

Columns

columns=2

Code

box = lambda text, w=90, h=44: pz.container(ui.label(text), center=True, width=w, height=h, bg=pz.theme.current().element, radius=6)
pz.container(pz.grid([box(str(i), w="fill") for i in range(1, 5)], columns=2, spacing=8, height=44), width=220)

columns=3

Code

box = lambda text, w=90, h=44: pz.container(ui.label(text), center=True, width=w, height=h, bg=pz.theme.current().element, radius=6)
pz.container(pz.grid([box(str(i), w="fill") for i in range(1, 7)], columns=3, spacing=8, height=44), width=300)

columns=4

Code

box = lambda text, w=90, h=44: pz.container(ui.label(text), center=True, width=w, height=h, bg=pz.theme.current().element, radius=6)
pz.container(pz.grid([box(str(i), w="fill") for i in range(1, 9)], columns=4, spacing=8, height=44), width=380)

Tracks

columns=[100, "1fr"]

Code

box = lambda text, w=90, h=44: pz.container(ui.label(text), center=True, width=w, height=h, bg=pz.theme.current().element, radius=6)
pz.container(pz.grid([box("100 px", w="fill"), box("1fr", w="fill")], columns=[100, "1fr"], spacing=8),
             width=340, height=44)

column_span=2

Code

box = lambda text, w=90, h=44: pz.container(ui.label(text), center=True, width=w, height=h, bg=pz.theme.current().element, radius=6)
pz.container(pz.grid([pz.cell(box("header", w="fill"), column=0, row=0, column_span=2),
                      pz.cell(box("a", w="fill"), column=0, row=1),
                      pz.cell(box("b", w="fill"), column=1, row=1)], columns=["1fr", "1fr"], spacing=8),
             width=300, height=96)

Examples

Tracks and spans

Numbers are pixels, "1fr" shares the free space and "auto" fits the content.

Preview

Code

box = lambda text, w=90, h=44: pz.container(ui.label(text), center=True, width=w, height=h, bg=pz.theme.current().element, radius=6)
pz.container(pz.grid([
    pz.cell(box("header", w="fill"), column=0, row=0, column_span=2),
    pz.cell(box("sidebar", w="fill", h="fill"), column=0, row=1),
    pz.cell(box("content", w="fill", h="fill"), column=1, row=1),
], columns=[120, "1fr"], rows=[44, 110], spacing=8), width=440)

Events

Grid has no events of its own: it shows what you give it. Like every widget it also has the 18 common events (click, double_click, right_click, mouse_enter, drag, key_down, resize…), attached with .on(...): see Events and Events of every component.

Properties and API

pz.grid

grid(
    children=None,
    *,
    columns=None,
    rows=None,
    max_width=None,
    spacing=0.0,
    row_spacing=None,
    height=None,
    aspect_ratio=None,
    width=None,
    padding=None,
    align_x=None,
    align_y=None,
)

Lays out its children in a grid. With columns=3 the columns are equal (or max_width fits as many as possible). With track lists (columns=[200, "1fr", "auto"], rows=...) it works like a CSS grid: numbers are pixels, "auto" fits the content and "<n>fr" shares the space left. Wrap children in pz.cell to place them and make them span; the rest fill the free cells row by row. See Layout.

Property	Default	Description
children	None	List of children. Nested lists are flattened and None and False are ignored, so you can write cond and widget.
columns	None	Number of equal columns, or tracks: a list ([200, "1fr", "auto"]) or a string ("200 1fr auto").
rows	None	Row tracks, like columns. Rows beyond the list are "auto".
max_width	None	Fits as many columns of at most this width as possible (columns=<int> only).
spacing	0.0	Space between cells.
row_spacing	None	Space between rows, if different.
height	None	With columns=<int>: height of each row. With tracks: the grid’s height.
aspect_ratio	None	Keeps cells at this width/height ratio (columns=<int> only).
width	None	With columns=<int>: pixels. With tracks: the grid’s width (default "fill").
padding	None	Space around the cells.
align_x	None	Horizontal alignment of items in their cells: "start", "center", "end".
align_y	None	Vertical alignment of items in their cells.

Full reference →

pz.cell

cell(
    content,
    *,
    column=None,
    row=None,
    column_span=1,
    row_span=1,
    align_x=None,
    align_y=None,
)

Places a child in a track grid: its column and row (from 0) and how many it spans. Children without a cell fill the free cells row by row. Outside a grid it is just the child.

Property	Default	Description
content	required	The widget.
column	None	Column index (from 0).
row	None	Row index (from 0).
column_span	1	Columns it covers.
row_span	1	Rows it covers.
align_x	None	Horizontal alignment in the cell.
align_y	None	Vertical alignment in the cell.

Full reference →

Related

FlexCSS flexbox: justify, align, gap, wrap and grow.

RowLays out children horizontally.

ColumnStacks children vertically.