Grid View

Grid views arrange content in a two-dimensional grid of rows and columns.

They are commonly used for dashboards and structured layouts where both horizontal and vertical positioning are required.

In most models you do not instantiate GridView directly. Instead, create it via the UiBuilder API, UiBuilder.add_grid_view(), which registers the view with the UI definition and ensures it is included in the build output.

class GridView(layout, display_name=None, hidden=False)[source]

Bases: CompositeView

A composite view that arranges child views using CSS Grid layout.

This view uses a GridLayout object to define grid template properties, providing a powerful and flexible way to position children within rows and columns.

Parameters:

layout (GridLayout) – The grid layout configuration that defines columns, rows, and areas.
display_name (str | None) – A human-readable name for this view. Defaults to None.
hidden (bool) – Whether the view is initially hidden. Defaults to False.
scroll_sync_enabled (bool, optional) – If True, enables synchronized scrolling with sibling views. Defaults to False.
justify_items (GridAlignment, optional) – Alignment of items along the inline (row) axis. Defaults to GridAlignment.START.
align_items (GridAlignment, optional) – Alignment of items along the block (column) axis. Defaults to GridAlignment.START.
gap (str, optional) – The gap between grid items (both rows and columns). Defaults to “5px”.
row_gap (Optional[str], optional) – Overrides the gap between rows if specified.
column_gap (Optional[str], optional) – Overrides the gap between columns if specified.

set_scroll_sync_enabled(enabled)[source]

Sets whether synchronized scrolling with sibling views is enabled.

Return type:: GridView

set_justify_items(justify_items)[source]

Sets the alignment of items along the inline (row) axis.

Return type:: GridView

set_align_items(align_items)[source]

Sets the alignment of items along the block (column) axis.

Return type:: GridView

set_gap(gap)[source]

Sets the gap between grid items.

Return type:: GridView

set_row_gap(row_gap)[source]

Sets the gap between rows.

Return type:: GridView

set_column_gap(column_gap)[source]

Sets the gap between columns.

Return type:: GridView

set_background_colour(colour)[source]

Sets the background colour of the grid view.

Return type:: GridView

set_padding(padding)[source]

Sets the padding of the grid view.

Return type:: GridView

add_child(view, exclude_default_styling=False, **kwargs)[source]

Adds a child view to this composite layout with flexible styling options.

Parameters:

view (BaseView) – The view to be added as a child within this composite layout.
exclude_default_styling (bool) – If True, default system styling for the child view will be skipped. Defaults to False.
**kwargs –
Keyword arguments that define style configuration for this child view. All keys must correspond to attributes of the GridChild class.

If a keyword does not match any attribute of GridChild, an AttributeError is raised.

Raises:

AttributeError – If any key in **kwargs does not match a valid GridChild attribute.

Example

>>> add_child(
...     view=some_view,
...     grid_area="header",
...     padding="1rem",
...     background_color="#f0f0f0"
... )

Supporting Types

class GridLayout(columns, rows, areas=None)[source]

Bases: object

Defines CSS Grid layout.

columns

Track sizing for columns, e.g., [“1fr”, “2fr”].

Type:: List[str]

rows

Track sizing for rows, e.g., [“auto”, “1fr”].

Type:: List[str]

areas

2D list of area names; must match row and column dimensions.

Type:: Optional[List[List[str]]]

columns: list[str]

rows: list[str]

areas: list[list[str]] | None = None

build()[source]

Return type:: dict

class GridChild(grid_column_start=None, grid_column_end=None, grid_row_start=None, grid_row_end=None, grid_area=None, justify_self=None, align_self=None, padding='unset', margin=None, border='none', border_radius=None, box_shadow='none', background_color=None, border_color=None, width='100%', height='100%')[source]

Bases: Buildable

Configuration options for a grid item inside a grid container.

grid_column_start

The starting grid column line where this item should be placed. Accepts an integer (e.g., 1), a string value (e.g., “auto” or “span 2”). Example: grid_column_start=2 places the item starting at the second vertical line.

Type:: Optional[str | int]

grid_column_end

The ending grid column line. Defines how many columns the item spans. Example: grid_column_end=”span 3” causes the item to span three columns.

Type:: Optional[str | int]

grid_row_start

The starting grid row line where this item should be placed. Accepts a number or string like “auto” or “span 2”. Example: grid_row_start=1 places the item at the top of the grid.

Type:: Optional[str | int]

grid_row_end

The ending grid row line. Defines how many rows the item spans. Example: grid_row_end=”span 2” causes the item to span two rows.

Type:: Optional[str | int]

grid_area

A named grid area that this item should occupy, defined in the parent container’s grid-template-areas.

Type:: Optional[str]

justify_self

Horizontal alignment of the item within its own grid cell. Overrides the container’s justify-items setting. Options: start, end, center, stretch.

Type:: Optional[JustifySelf]

align_self

Vertical alignment of the item within its own grid cell. Overrides the container’s align-items setting. Options: start, end, center, stretch.

Type:: Optional[GridAlignment]

padding

Space between the item’s content and its border. Can be specified in CSS units (e.g., “1rem”, “10px”).

Type:: Optional[str | int]

margin

Space outside the item, separating it from other elements. Can be specified in CSS units.

Type:: Optional[str | int]

border

Defines the item’s border. Accepts any valid CSS border definition. Example: “1px solid #ccc”.

Type:: Optional[str]

border_radius

Rounds the corners of the item’s border. Example: “4px” or “0.5rem”.

Type:: Optional[str | int]

box_shadow

Applies a shadow effect around the item. Example: “0 1px 3px rgba(0,0,0,0.2)”.

Type:: Optional[str]

background_color

Sets the background color of the item. Can be any valid CSS color (hex, rgb, named, etc.). Example: “#ffffff” or “rgba(0,0,0,0.1)”.

Type:: Optional[str]

grid_column_start: str | int | None = None

grid_column_end: str | int | None = None

grid_row_start: str | int | None = None

grid_row_end: str | int | None = None

grid_area: str | None = None

justify_self: GridAlignment | None = None

align_self: GridAlignment | None = None

padding: str | int | None = 'unset'

margin: str | int | None = None

border: str | None = 'none'

border_radius: str | int | None = None

box_shadow: str | None = 'none'

background_color: str | None = None

border_color: str | None = None

width: str = '100%'

height: str = '100%'

class GridAlignment(*values)[source]

Bases: Enum

Defines the default alignment of items inside a grid container.

START: Items are aligned to the start of the cell.

END: Items are aligned to the end of the cell.

CENTER: Items are centered within the cell.

STRETCH: Items stretch to fill the entire space of the cell.

START = 'start'

END = 'end'

CENTER = 'center'

STRETCH = 'stretch'