---
source: crates/tinymist-query/src/hover.rs
expression: content
input_file: crates/tinymist-query/src/fixtures/hover/builtin.typ
---
Range: 0:20:0:25
```typc
let table(
..children: content,
align: alignment | array | auto | function = auto,
column-gutter: array | auto | length | type = (),
columns: array | auto | length | type = (),
fill: color = none,
gutter: array | auto | length | type = (),
inset: inset = 0% + 5pt,
row-gutter: array | auto | length | type = (),
rows: array | auto | length | type = (),
stroke: stroke = 1pt + black,
);
```
======
A table of items.
Tables are used to arrange content in cells. Cells can contain arbitrary content, including multiple paragraphs and are specified in row-major order. For a hands-on explanation of all the ways you can use and customize tables in Typst, check out the Table Guide.
Because tables are just grids with different defaults for some cell properties (notably `stroke` and `inset`), refer to the grid documentation for more information on how to size the table tracks and specify the cell appearance properties.
If you are unsure whether you should be using a table or a grid, consider whether the content you are arranging semantically belongs together as a set of related data points or similar or whether you are just want to enhance your presentation by arranging unrelated content in a grid. In the former case, a table is the right choice, while in the latter case, a grid is more appropriate. Furthermore, Assistive Technology (AT) like screen readers will announce content in a `table` as tabular while a grid’s content will be announced no different than multiple content blocks in the document flow. AT users will be able to navigate tables two-dimensionally by cell.
Note that, to override a particular cell’s properties or apply show rules on table cells, you can use the [table.cell](https://typst.app/docs/reference/model/table/#definitions-cell) element. See its documentation for more information.
Although the `table` and the `grid` share most properties, set and show rules on one of them do not affect the other. Locating most of your styling in set and show rules is recommended, as it keeps the table’s actual usages clean and easy to read. It also allows you to easily change the appearance of all tables in one place.
To give a table a caption and make it [referenceable](https://typst.app/docs/reference/model/ref/), put it into a [figure](https://typst.app/docs/reference/model/figure/).
## Example
The example below demonstrates some of the most common table options.
```typ
#table(
columns: (1fr, auto, auto),
inset: 10pt,
align: horizon,
table.header(
[], [*Volume*], [*Parameters*],
),
image("cylinder.svg"),
$ pi h (D^2 - d^2) / 4 $,
[
$h$: height \
$D$: outer radius \
$d$: inner radius
],
image("tetrahedron.svg"),
$ sqrt(2) / 12 a^3 $,
[$a$: edge length]
)
```
Much like with grids, you can use [table.cell](https://typst.app/docs/reference/model/table/#definitions-cell) to customize the appearance and the position of each cell.
```typ
>>> #set page(width: auto)
>>> #set text(font: "IBM Plex Sans")
>>> #let gray = rgb("#565565")
>>>
#set table(
stroke: none,
gutter: 0.2em,
fill: (x, y) =>
if x == 0 or y == 0 { gray },
inset: (right: 1.5em),
)
#show table.cell: it => {
if it.x == 0 or it.y == 0 {
set text(white)
strong(it)
} else if it.body == [] {
// Replace empty cells with 'N/A'
pad(..it.inset)[_N/A_]
} else {
it
}
}
#let a = table.cell(
fill: green.lighten(60%),
)[A]
#let b = table.cell(
fill: aqua.lighten(60%),
)[B]
#table(
columns: 4,
[], [Exam 1], [Exam 2], [Exam 3],
[John], [], a, [],
[Mary], [], a, a,
[Robert], b, a, b,
)
```
## Accessibility
Tables are challenging to consume for users of Assistive Technology (AT). To make the life of AT users easier, we strongly recommend that you use [table.header](https://typst.app/docs/reference/model/table/#definitions-header) and [table.footer](https://typst.app/docs/reference/model/table/#definitions-footer) to mark the header and footer sections of your table. This will allow AT to announce the column labels for each cell.
Because navigating a table by cell is more cumbersome than reading it visually, you should consider making the core information in your table available as text as well. You can do this by wrapping your table in a [figure](https://typst.app/docs/reference/model/figure/) and using its caption to summarize the table’s content.
# Rest Parameters
## children
```typc
type: content
```
The contents of the table cells, plus any extra table lines specified with the [table.hline](https://typst.app/docs/reference/model/table/#definitions-hline) and [table.vline](https://typst.app/docs/reference/model/table/#definitions-vline) elements.
# Named Parameters
## align
```typc
type: alignment | array | auto | function
```
How to align the cells’ content.
If set to `auto`, the outer alignment is used.
You can specify the alignment in any of the following fashions:
- use a single alignment for all cells
- use an array of alignments corresponding to each column
- use a function that maps a cell’s X/Y position (both starting from zero) to its alignment
See the Table Guide for details.
```typ
#table(
columns: 3,
align: (left, center, right),
[Hello], [Hello], [Hello],
[A], [B], [C],
)
```
## column-gutter (named)
```typc
type: array | auto | length | type
```
The gaps between columns. Takes precedence over `gutter`. See the [grid documentation](https://typst.app/docs/reference/layout/grid/#parameters-gutter) for more information on gutters.
## columns (named)
```typc
type: array | auto | length | type
```
The column sizes. See the grid documentation for more information on track sizing.
## fill (named)
```typc
type: color
```
How to fill the cells.
This can be:
- a single fill for all cells
- an array of fill corresponding to each column
- a function that maps a cell’s position to its fill
Most notably, arrays and functions are useful for creating striped tables. See the Table Guide for more details.
```typ
#table(
fill: (x, _) =>
if calc.odd(x) { luma(240) }
else { white },
align: (x, y) =>
if y == 0 { center }
else if x == 0 { left }
else { right },
columns: 4,
[], [*Q1*], [*Q2*], [*Q3*],
[Revenue:], [1000 €], [2000 €], [3000 €],
[Expenses:], [500 €], [1000 €], [1500 €],
[Profit:], [500 €], [1000 €], [1500 €],
)
```
## gutter (named)
```typc
type: array | auto | length | type
```
The gaps between rows and columns. This is a shorthand for setting `column-gutter` and `row-gutter` to the same value. See the [grid documentation](https://typst.app/docs/reference/layout/grid/#parameters-gutter) for more information on gutters.
## inset (named)
```typc
type: inset
```
How much to pad the cells’ content.
To specify the same inset for all cells, use a single length for all sides, or a dictionary of lengths for individual sides. See the [box’s documentation](https://typst.app/docs/reference/layout/box/#parameters-inset) for more details.
To specify a varying inset for different cells, you can:
- use a single, uniform inset for all cells
- use an array of insets for each column
- use a function that maps a cell’s X/Y position (both starting from zero) to its inset
See the grid documentation for more details.
```typ
#table(
columns: 2,
inset: 10pt,
[Hello],
[World],
)
#table(
columns: 2,
inset: (x: 20pt, y: 10pt),
[Hello],
[World],
)
```
## row-gutter (named)
```typc
type: array | auto | length | type
```
The gaps between rows. Takes precedence over `gutter`. See the [grid documentation](https://typst.app/docs/reference/layout/grid/#parameters-gutter) for more information on gutters.
## rows (named)
```typc
type: array | auto | length | type
```
The row sizes. See the grid documentation for more information on track sizing.
## stroke (named)
```typc
type: stroke
```
How to [stroke](https://typst.app/docs/reference/visualize/stroke/) the cells.
Strokes can be disabled by setting this to `none`.
If it is necessary to place lines which can cross spacing between cells produced by the [`gutter`](https://typst.app/docs/reference/model/table/#parameters-gutter) option, or to override the stroke between multiple specific cells, consider specifying one or more of [table.hline](https://typst.app/docs/reference/model/table/#definitions-hline) and [table.vline](https://typst.app/docs/reference/model/table/#definitions-vline) alongside your table cells.
To specify the same stroke for all cells, use a single [stroke](https://typst.app/docs/reference/visualize/stroke/) for all sides, or a dictionary of [strokes](https://typst.app/docs/reference/visualize/stroke/) for individual sides. See the [rectangle’s documentation](https://typst.app/docs/reference/visualize/rect/#parameters-stroke) for more details.
To specify varying strokes for different cells, you can:
- use a single stroke for all cells
- use an array of strokes corresponding to each column
- use a function that maps a cell’s position to its stroke
See the Table Guide for more details.
======
[Open docs](https://typst.app/docs/reference/model/table/)