Skip to content


There are a number of properties relating to the Textual grid layout.

For an in-depth look at the grid layout, visit the grid guide.

Property Description
grid-size Number of columns and rows in the grid layout.
grid-rows Height of grid rows.
grid-columns Width of grid columns.
grid-gutter Spacing between grid cells.
row-span Number of rows a cell spans.
column-span Number of columns a cell spans.


grid-size: <INTEGER> [<INTEGER>];
/* columns first, then rows */
grid-rows: <SCALAR> . . .;
grid-columns: <SCALAR> . . .;
grid-gutter: <SCALAR>;
row-span: <INTEGER>;
column-span: <INTEGER>;


The example below shows all the properties above in action. The grid-size: 3 4; declaration sets the grid to 3 columns and 4 rows. The first cell of the grid, tinted magenta, shows a cell spanning multiple rows and columns. The spacing between grid cells is because of the grid-gutter declaration.

GridApp Grid cell 1Grid cell 2 row-span: 3; column-span: 2; Grid cell 3 Grid cell 4 Grid cell 5Grid cell 6Grid cell 7

from import App
from textual.widgets import Static

class GridApp(App):
    def compose(self):
        yield Static("Grid cell 1\n\nrow-span: 3;\ncolumn-span: 2;", id="static1")
        yield Static("Grid cell 2", id="static2")
        yield Static("Grid cell 3", id="static3")
        yield Static("Grid cell 4", id="static4")
        yield Static("Grid cell 5", id="static5")
        yield Static("Grid cell 6", id="static6")
        yield Static("Grid cell 7", id="static7")

app = GridApp(css_path="grid.css")
Screen {
    layout: grid;
    grid-size: 3 4;
    grid-rows: 1fr;
    grid-columns: 1fr;
    grid-gutter: 1;

Static {
    color: auto;
    background: lightblue;
    height: 100%;
    padding: 1 2;

#static1 {
    tint: magenta 40%;
    row-span: 3;
    column-span: 2;


The properties listed on this page will only work when the layout is grid.