{"route":"/en-US-v0.13.1/reference/layout/grid/","title":"Grid","description":"Documentation for the `grid` function.","part":null,"outline":[{"id":"summary","name":"Summary","children":[]},{"id":"examples","name":"Examples","children":[]},{"id":"styling-the-grid","name":"Styling the grid","children":[{"id":"stroke-styling-precedence","name":"Stroke styling precedence","children":[]}]},{"id":"parameters","name":"Parameters","children":[{"id":"parameters-columns","name":"columns","children":[]},{"id":"parameters-rows","name":"rows","children":[]},{"id":"parameters-gutter","name":"gutter","children":[]},{"id":"parameters-column-gutter","name":"column-gutter","children":[]},{"id":"parameters-row-gutter","name":"row-gutter","children":[]},{"id":"parameters-fill","name":"fill","children":[]},{"id":"parameters-align","name":"align","children":[]},{"id":"parameters-stroke","name":"stroke","children":[]},{"id":"parameters-inset","name":"inset","children":[]},{"id":"parameters-children","name":"children","children":[]}]},{"id":"definitions","name":"Definitions","children":[{"id":"definitions-cell","name":"Grid Cell","children":[{"id":"definitions-cell-body","name":"body","children":[]},{"id":"definitions-cell-x","name":"x","children":[]},{"id":"definitions-cell-y","name":"y","children":[]},{"id":"definitions-cell-colspan","name":"colspan","children":[]},{"id":"definitions-cell-rowspan","name":"rowspan","children":[]},{"id":"definitions-cell-fill","name":"fill","children":[]},{"id":"definitions-cell-align","name":"align","children":[]},{"id":"definitions-cell-inset","name":"inset","children":[]},{"id":"definitions-cell-stroke","name":"stroke","children":[]},{"id":"definitions-cell-breakable","name":"breakable","children":[]}]},{"id":"definitions-hline","name":"Grid Horizontal Line","children":[{"id":"definitions-hline-y","name":"y","children":[]},{"id":"definitions-hline-start","name":"start","children":[]},{"id":"definitions-hline-end","name":"end","children":[]},{"id":"definitions-hline-stroke","name":"stroke","children":[]},{"id":"definitions-hline-position","name":"position","children":[]}]},{"id":"definitions-vline","name":"Grid Vertical Line","children":[{"id":"definitions-vline-x","name":"x","children":[]},{"id":"definitions-vline-start","name":"start","children":[]},{"id":"definitions-vline-end","name":"end","children":[]},{"id":"definitions-vline-stroke","name":"stroke","children":[]},{"id":"definitions-vline-position","name":"position","children":[]}]},{"id":"definitions-header","name":"Grid Header","children":[{"id":"definitions-header-repeat","name":"repeat","children":[]},{"id":"definitions-header-children","name":"children","children":[]}]},{"id":"definitions-footer","name":"Grid Footer","children":[{"id":"definitions-footer-repeat","name":"repeat","children":[]},{"id":"definitions-footer-children","name":"children","children":[]}]}]}],"body":{"kind":"func","content":{"path":[],"name":"grid","title":"Grid","keywords":[],"oneliner":"Arranges content in a grid.","element":true,"contextual":false,"deprecation":null,"details":"

Arranges content in a grid.

\n

The grid element allows you to arrange content in a grid. You can define the\nnumber of rows and columns, as well as the size of the gutters between them.\nThere are multiple sizing modes for columns and rows that can be used to\ncreate complex layouts.

\n

While the grid and table elements work very similarly, they are intended for\ndifferent use cases and carry different semantics. The grid element is\nintended for presentational and layout purposes, while the\ntable element is intended for, in broad terms, presenting\nmultiple related data points. In the future, Typst will annotate its output\nsuch that screenreaders will announce content in table as tabular while a\ngrid's content will be announced no different than multiple content blocks\nin the document flow. Set and show rules on one of these elements do not\naffect the other.

\n

A grid's sizing is determined by the track sizes specified in the arguments.\nBecause each of the sizing parameters accepts the same values, we will\nexplain them just once, here. Each sizing argument accepts an array of\nindividual track sizes. A track size is either:

\n\n

To specify a single track, the array can be omitted in favor of a single\nvalue. To specify multiple auto tracks, enter the number of tracks\ninstead of an array. For example, columns: 3 is equivalent to\ncolumns: (auto, auto, auto).

\n

Examples

\n

The example below demonstrates the different track sizing options. It also\nshows how you can use grid.cell to make an individual cell\nspan two grid tracks.

\n
// We use `rect` to emphasize the\n// area of cells.\n#set rect(\n  inset: 8pt,\n  fill: rgb("e4e5ea"),\n  width: 100%,\n)\n\n#grid(\n  columns: (60pt, 1fr, 2fr),\n  rows: (auto, 60pt),\n  gutter: 3pt,\n  rect[Fixed width, auto height],\n  rect[1/3 of the remains],\n  rect[2/3 of the remains],\n  rect(height: 100%)[Fixed height],\n  grid.cell(\n    colspan: 2,\n    image("tiger.jpg", width: 100%),\n  ),\n)\n
\"Preview\"
\n

You can also spread an array of strings or content\ninto a grid to populate its cells.

\n
#grid(\n  columns: 5,\n  gutter: 5pt,\n  ..range(25).map(str)\n)\n
\"Preview\"
\n

Styling the grid

\n

The grid's appearance can be customized through different parameters. These\nare the most important ones:

\n\n

If you need to override one of the above options for a single cell, you can\nuse the grid.cell element. Likewise, you can override\nindividual grid lines with the grid.hline and\ngrid.vline elements.

\n

Alternatively, if you need the appearance options to depend on a cell's\nposition (column and row), you may specify a function to fill or align\nof the form (column, row) => value. You may also use a show rule on\ngrid.cell - see that element's examples or the examples\nbelow for more information.

\n

Locating most of your styling in set and show rules is recommended, as it\nkeeps the grid's or table's actual usages clean and easy to read. It also\nallows you to easily change the grid's appearance in one place.

\n

Stroke styling precedence

\n

There are three ways to set the stroke of a grid cell: through\ngrid.cell's stroke field, by using\ngrid.hline and grid.vline, or by\nsetting the grid's stroke field. When multiple of\nthese settings are present and conflict, the hline and vline settings\ntake the highest precedence, followed by the cell settings, and finally\nthe grid settings.

\n

Furthermore, strokes of a repeated grid header or footer will take\nprecedence over regular cell strokes.

","example":null,"self":false,"params":[{"name":"columns","details":"

The column sizes.

\n

Either specify a track size array or provide an integer to create a grid\nwith that many auto-sized columns. Note that opposed to rows and\ngutters, providing a single track size will only ever create a single\ncolumn.

","example":null,"types":["auto","int","relative","fraction","array"],"strings":[],"default":"()","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"rows","details":"

The row sizes.

\n

If there are more cells than fit the defined rows, the last row is\nrepeated until there are no more cells.

","example":null,"types":["auto","int","relative","fraction","array"],"strings":[],"default":"()","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"gutter","details":"

The gaps between rows and columns.

\n

If there are more gutters than defined sizes, the last gutter is\nrepeated.

\n

This is a shorthand to set column-gutter and row-gutter to the same\nvalue.

","example":null,"types":["auto","int","relative","fraction","array"],"strings":[],"default":"()","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"column-gutter","details":"

The gaps between columns.

","example":null,"types":["auto","int","relative","fraction","array"],"strings":[],"default":"()","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"row-gutter","details":"

The gaps between rows.

","example":null,"types":["auto","int","relative","fraction","array"],"strings":[],"default":"()","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"fill","details":"

How to fill the cells.

\n

This can be a color or a function that returns a color. The function\nreceives the cells' column and row indices, starting from zero. This can\nbe used to implement striped grids.

","example":"
#grid(\n  fill: (x, y) =>\n    if calc.even(x + y) { luma(230) }\n    else { white },\n  align: center + horizon,\n  columns: 4,\n  inset: 2pt,\n  [X], [O], [X], [O],\n  [O], [X], [O], [X],\n  [X], [O], [X], [O],\n  [O], [X], [O], [X],\n)\n
\"Preview\"
","types":["none","color","gradient","array","tiling","function"],"strings":[],"default":"none","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"align","details":"

How to align the cells' content.

\n

This can either be a single alignment, an array of alignments\n(corresponding to each column) or a function that returns an alignment.\nThe function receives the cells' column and row indices, starting from\nzero. If set to auto, the outer alignment is used.

\n

You can find an example for this argument at the\ntable.align parameter.

","example":null,"types":["auto","array","alignment","function"],"strings":[],"default":"auto","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"stroke","details":"

How to stroke the cells.

\n

Grids have no strokes by default, which can be changed by setting this\noption to the desired stroke.

\n

If it is necessary to place lines which can cross spacing between cells\nproduced by the gutter option, or to override the stroke between\nmultiple specific cells, consider specifying one or more of\ngrid.hline and grid.vline alongside\nyour grid cells.

","example":"
#set page(height: 13em, width: 26em)\n\n#let cv(..jobs) = grid(\n  columns: 2,\n  inset: 5pt,\n  stroke: (x, y) => if x == 0 and y > 0 {\n    (right: (\n      paint: luma(180),\n      thickness: 1.5pt,\n      dash: "dotted"\n    ))\n  },\n  grid.header(grid.cell(colspan: 2)[\n    *Professional Experience*\n    #box(width: 1fr, line(length: 100%, stroke: luma(180)))\n  ]),\n  ..{\n    let last = none\n    for job in jobs.pos() {\n      (\n        if job.year != last [*#job.year*],\n        [\n          *#job.company* - #job.role _(#job.timeframe)_ \\\n          #job.details\n        ]\n      )\n      last = job.year\n    }\n  }\n)\n\n#cv(\n  (\n    year: 2012,\n    company: [Pear Seed & Co.],\n    role: [Lead Engineer],\n    timeframe: [Jul - Dec],\n    details: [\n      - Raised engineers from 3x to 10x\n      - Did a great job\n    ],\n  ),\n  (\n    year: 2012,\n    company: [Mega Corp.],\n    role: [VP of Sales],\n    timeframe: [Mar - Jun],\n    details: [- Closed tons of customers],\n  ),\n  (\n    year: 2013,\n    company: [Tiny Co.],\n    role: [CEO],\n    timeframe: [Jan - Dec],\n    details: [- Delivered 4x more shareholder value],\n  ),\n  (\n    year: 2014,\n    company: [Glorbocorp Ltd],\n    role: [CTO],\n    timeframe: [Jan - Mar],\n    details: [- Drove containerization forward],\n  ),\n)\n
\"Preview\"
","types":["none","length","color","gradient","array","stroke","tiling","dictionary","function"],"strings":[],"default":"(:)","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"inset","details":"

How much to pad the cells' content.

\n

You can find an example for this argument at the\ntable.inset parameter.

","example":null,"types":["relative","array","dictionary","function"],"strings":[],"default":"(:)","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"children","details":"

The contents of the grid cells, plus any extra grid lines specified\nwith the grid.hline and grid.vline\nelements.

\n

The cells are populated in row-major order.

","example":null,"types":["content"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":true,"settable":false}],"returns":["content"],"scope":[{"path":["grid"],"name":"cell","title":"Grid Cell","keywords":[],"oneliner":"A cell in the grid. You can use this function in the argument list of a grid","element":true,"contextual":false,"deprecation":null,"details":"

A cell in the grid. You can use this function in the argument list of a grid\nto override grid style properties for an individual cell or manually\npositioning it within the grid. You can also use this function in show rules\nto apply certain styles to multiple cells at once.

\n

For example, you can override the position and stroke for a single cell:

","example":"
#set text(15pt, font: "Noto Sans Symbols 2")\n#show regex("[♚-♟︎]"): set text(fill: rgb("21212A"))\n#show regex("[♔-♙]"): set text(fill: rgb("111015"))\n\n#grid(\n  fill: (x, y) => rgb(\n    if calc.odd(x + y) { "7F8396" }\n    else { "EFF0F3" }\n  ),\n  columns: (1em,) * 8,\n  rows: 1em,\n  align: center + horizon,\n\n  [♖], [♘], [♗], [♕], [♔], [♗], [♘], [♖],\n  [♙], [♙], [♙], [♙], [],  [♙], [♙], [♙],\n  grid.cell(\n    x: 4, y: 3,\n    stroke: blue.transparentize(60%)\n  )[♙],\n\n  ..(grid.cell(y: 6)[♟],) * 8,\n  ..([♜], [♞], [♝], [♛], [♚], [♝], [♞], [♜])\n    .map(grid.cell.with(y: 7)),\n)\n
\"Preview\"
\n

You may also apply a show rule on grid.cell to style all cells at once,\nwhich allows you, for example, to apply styles based on a cell's position.\nRefer to the examples of the table.cell element to learn\nmore about this.

","self":false,"params":[{"name":"body","details":"

The cell's body.

","example":null,"types":["content"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":false,"settable":false},{"name":"x","details":"

The cell's column (zero-indexed).\nThis field may be used in show rules to style a cell depending on its\ncolumn.

\n

You may override this field to pick in which column the cell must\nbe placed. If no row (y) is chosen, the cell will be placed in the\nfirst row (starting at row 0) with that column available (or a new row\nif none). If both x and y are chosen, however, the cell will be\nplaced in that exact position. An error is raised if that position is\nnot available (thus, it is usually wise to specify cells with a custom\nposition before cells with automatic positions).

","example":"
#let circ(c) = circle(\n    fill: c, width: 5mm\n)\n\n#grid(\n  columns: 4,\n  rows: 7mm,\n  stroke: .5pt + blue,\n  align: center + horizon,\n  inset: 1mm,\n\n  grid.cell(x: 2, y: 2, circ(aqua)),\n  circ(yellow),\n  grid.cell(x: 3, circ(green)),\n  circ(black),\n)\n
\"Preview\"
","types":["auto","int"],"strings":[],"default":"auto","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"y","details":"

The cell's row (zero-indexed).\nThis field may be used in show rules to style a cell depending on its\nrow.

\n

You may override this field to pick in which row the cell must be\nplaced. If no column (x) is chosen, the cell will be placed in the\nfirst column (starting at column 0) available in the chosen row. If all\ncolumns in the chosen row are already occupied, an error is raised.

","example":"
#let tri(c) = polygon.regular(\n  fill: c,\n  size: 5mm,\n  vertices: 3,\n)\n\n#grid(\n  columns: 2,\n  stroke: blue,\n  inset: 1mm,\n\n  tri(black),\n  grid.cell(y: 1, tri(teal)),\n  grid.cell(y: 1, tri(red)),\n  grid.cell(y: 2, tri(orange))\n)\n
\"Preview\"
","types":["auto","int"],"strings":[],"default":"auto","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"colspan","details":"

The amount of columns spanned by this cell.

","example":null,"types":["int"],"strings":[],"default":"1","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"rowspan","details":"

The amount of rows spanned by this cell.

","example":null,"types":["int"],"strings":[],"default":"1","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"fill","details":"

The cell's fill override.

","example":null,"types":["none","auto","color","gradient","tiling"],"strings":[],"default":"auto","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"align","details":"

The cell's alignment override.

","example":null,"types":["auto","alignment"],"strings":[],"default":"auto","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"inset","details":"

The cell's inset override.

","example":null,"types":["auto","relative","dictionary"],"strings":[],"default":"auto","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"stroke","details":"

The cell's stroke override.

","example":null,"types":["none","length","color","gradient","stroke","tiling","dictionary"],"strings":[],"default":"(:)","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"breakable","details":"

Whether rows spanned by this cell can be placed in different pages.\nWhen equal to auto, a cell spanning only fixed-size rows is\nunbreakable, while a cell spanning at least one auto-sized row is\nbreakable.

","example":null,"types":["auto","bool"],"strings":[],"default":"auto","positional":false,"named":true,"required":false,"variadic":false,"settable":true}],"returns":["content"],"scope":[]},{"path":["grid"],"name":"hline","title":"Grid Horizontal Line","keywords":[],"oneliner":"A horizontal line in the grid.","element":true,"contextual":false,"deprecation":null,"details":"

A horizontal line in the grid.

\n

Overrides any per-cell stroke, including stroke specified through the grid's\nstroke field. Can cross spacing between cells created through the grid's\ncolumn-gutter option.

\n

An example for this function can be found at the\ntable.hline element.

","example":null,"self":false,"params":[{"name":"y","details":"

The row above which the horizontal line is placed (zero-indexed).\nIf the position field is set to bottom, the line is placed below\nthe row with the given index instead (see that field's docs for\ndetails).

\n

Specifying auto causes the line to be placed at the row below the\nlast automatically positioned cell (that is, cell without coordinate\noverrides) before the line among the grid's children. If there is no\nsuch cell before the line, it is placed at the top of the grid (row 0).\nNote that specifying for this option exactly the total amount of rows\nin the grid causes this horizontal line to override the bottom border\nof the grid, while a value of 0 overrides the top border.

","example":null,"types":["auto","int"],"strings":[],"default":"auto","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"start","details":"

The column at which the horizontal line starts (zero-indexed, inclusive).

","example":null,"types":["int"],"strings":[],"default":"0","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"end","details":"

The column before which the horizontal line ends (zero-indexed,\nexclusive).\nTherefore, the horizontal line will be drawn up to and across column\nend - 1.

\n

A value equal to none or to the amount of columns causes it to\nextend all the way towards the end of the grid.

","example":null,"types":["none","int"],"strings":[],"default":"none","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"stroke","details":"

The line's stroke.

\n

Specifying none removes any lines previously placed across this\nline's range, including hlines or per-cell stroke below it.

","example":null,"types":["none","length","color","gradient","stroke","tiling","dictionary"],"strings":[],"default":"1pt + black","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"position","details":"

The position at which the line is placed, given its row (y) - either\ntop to draw above it or bottom to draw below it.

\n

This setting is only relevant when row gutter is enabled (and\nshouldn't be used otherwise - prefer just increasing the y field by\none instead), since then the position below a row becomes different\nfrom the position above the next row due to the spacing between both.

","example":null,"types":["alignment"],"strings":[],"default":"top","positional":false,"named":true,"required":false,"variadic":false,"settable":true}],"returns":["content"],"scope":[]},{"path":["grid"],"name":"vline","title":"Grid Vertical Line","keywords":[],"oneliner":"A vertical line in the grid.","element":true,"contextual":false,"deprecation":null,"details":"

A vertical line in the grid.

\n

Overrides any per-cell stroke, including stroke specified through the\ngrid's stroke field. Can cross spacing between cells created through\nthe grid's row-gutter option.

","example":null,"self":false,"params":[{"name":"x","details":"

The column before which the horizontal line is placed (zero-indexed).\nIf the position field is set to end, the line is placed after the\ncolumn with the given index instead (see that field's docs for\ndetails).

\n

Specifying auto causes the line to be placed at the column after\nthe last automatically positioned cell (that is, cell without\ncoordinate overrides) before the line among the grid's children. If\nthere is no such cell before the line, it is placed before the grid's\nfirst column (column 0).\nNote that specifying for this option exactly the total amount of\ncolumns in the grid causes this vertical line to override the end\nborder of the grid (right in LTR, left in RTL), while a value of 0\noverrides the start border (left in LTR, right in RTL).

","example":null,"types":["auto","int"],"strings":[],"default":"auto","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"start","details":"

The row at which the vertical line starts (zero-indexed, inclusive).

","example":null,"types":["int"],"strings":[],"default":"0","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"end","details":"

The row on top of which the vertical line ends (zero-indexed,\nexclusive).\nTherefore, the vertical line will be drawn up to and across row\nend - 1.

\n

A value equal to none or to the amount of rows causes it to extend\nall the way towards the bottom of the grid.

","example":null,"types":["none","int"],"strings":[],"default":"none","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"stroke","details":"

The line's stroke.

\n

Specifying none removes any lines previously placed across this\nline's range, including vlines or per-cell stroke below it.

","example":null,"types":["none","length","color","gradient","stroke","tiling","dictionary"],"strings":[],"default":"1pt + black","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"position","details":"

The position at which the line is placed, given its column (x) -\neither start to draw before it or end to draw after it.

\n

The values left and right are also accepted, but discouraged as\nthey cause your grid to be inconsistent between left-to-right and\nright-to-left documents.

\n

This setting is only relevant when column gutter is enabled (and\nshouldn't be used otherwise - prefer just increasing the x field by\none instead), since then the position after a column becomes different\nfrom the position before the next column due to the spacing between\nboth.

","example":null,"types":["alignment"],"strings":[],"default":"start","positional":false,"named":true,"required":false,"variadic":false,"settable":true}],"returns":["content"],"scope":[]},{"path":["grid"],"name":"header","title":"Grid Header","keywords":[],"oneliner":"A repeatable grid header.","element":true,"contextual":false,"deprecation":null,"details":"

A repeatable grid header.

\n

If repeat is set to true, the header will be repeated across pages. For\nan example, refer to the table.header element and the\ngrid.stroke parameter.

","example":null,"self":false,"params":[{"name":"repeat","details":"

Whether this header should be repeated across pages.

","example":null,"types":["bool"],"strings":[],"default":"true","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"children","details":"

The cells and lines within the header.

","example":null,"types":["content"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":true,"settable":false}],"returns":["content"],"scope":[]},{"path":["grid"],"name":"footer","title":"Grid Footer","keywords":[],"oneliner":"A repeatable grid footer.","element":true,"contextual":false,"deprecation":null,"details":"

A repeatable grid footer.

\n

Just like the grid.header element, the footer can repeat\nitself on every page of the table.

\n

No other grid cells may be placed after the footer.

","example":null,"self":false,"params":[{"name":"repeat","details":"

Whether this footer should be repeated across pages.

","example":null,"types":["bool"],"strings":[],"default":"true","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"children","details":"

The cells and lines within the footer.

","example":null,"types":["content"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":true,"settable":false}],"returns":["content"],"scope":[]}]}}}