A table of items.
\nTables are used to arrange content in cells. Cells can contain arbitrary\ncontent, including multiple paragraphs and are specified in row-major order.\nFor a hands-on explanation of all the ways you can use and customize tables\nin Typst, check out the Table Guide.
\nBecause tables are just grids with different defaults for some cell\nproperties (notably stroke and inset), refer to the grid\ndocumentation for more information on how to size the\ntable tracks and specify the cell appearance properties.
If you are unsure whether you should be using a table or a grid, consider\nwhether the content you are arranging semantically belongs together as a set\nof related data points or similar or whether you are just want to enhance\nyour presentation by arranging unrelated content in a grid. In the former\ncase, a table is the right choice, while in the latter case, a grid is more\nappropriate. Furthermore, Assistive Technology (AT) like screen readers will\nannounce content in a table as tabular while a grid's content will be\nannounced no different than multiple content blocks in the document flow. AT\nusers will be able to navigate tables two-dimensionally by cell.
Note that, to override a particular cell's properties or apply show rules on\ntable cells, you can use the table.cell element. See its documentation\nfor more information.
Although the table and the grid share most properties, set and show\nrules on one of them do not affect the other. Locating most of your styling\nin set and show rules is recommended, as it keeps the table's actual usages\nclean and easy to read. It also allows you to easily change the appearance\nof all tables in one place.
To give a table a caption and make it referenceable, put it into a\nfigure.
\nThe example below demonstrates some of the most common table options.
\n#table(\n columns: (1fr, auto, auto),\n inset: 10pt,\n align: horizon,\n table.header(\n [], [*Volume*], [*Parameters*],\n ),\n image("cylinder.svg"),\n $ pi h (D^2 - d^2) / 4 $,\n [\n $h$: height \\\n $D$: outer radius \\\n $d$: inner radius\n ],\n image("tetrahedron.svg"),\n $ sqrt(2) / 12 a^3 $,\n [$a$: edge length]\n)\n![\"Preview\"](\"/en-US-v0.14.1/assets/292ce306c3aab6e773c2f2ba66fa7dbb.png\")
Much like with grids, you can use table.cell to customize the appearance\nand the position of each cell.
#set table(\n stroke: none,\n gutter: 0.2em,\n fill: (x, y) =>\n if x == 0 or y == 0 { gray },\n inset: (right: 1.5em),\n)\n\n#show table.cell: it => {\n if it.x == 0 or it.y == 0 {\n set text(white)\n strong(it)\n } else if it.body == [] {\n // Replace empty cells with 'N/A'\n pad(..it.inset)[_N/A_]\n } else {\n it\n }\n}\n\n#let a = table.cell(\n fill: green.lighten(60%),\n)[A]\n#let b = table.cell(\n fill: aqua.lighten(60%),\n)[B]\n\n#table(\n columns: 4,\n [], [Exam 1], [Exam 2], [Exam 3],\n\n [John], [], a, [],\n [Mary], [], a, a,\n [Robert], b, a, b,\n)\n![\"Preview\"](\"/en-US-v0.14.1/assets/ffc1843d36a9bc64fabab2c809c2265.png\")
Tables are challenging to consume for users of Assistive Technology (AT). To\nmake the life of AT users easier, we strongly recommend that you use\ntable.header and table.footer to mark the header and footer sections\nof your table. This will allow AT to announce the column labels for each\ncell.
Because navigating a table by cell is more cumbersome than reading it\nvisually, you should consider making the core information in your table\navailable as text as well. You can do this by wrapping your table in a\nfigure and using its caption to summarize the table's content.
"}],"self":false,"params":[{"name":"columns","details":[{"kind":"html","content":"The column sizes. See the grid documentation for\nmore information on track sizing.
"}],"types":["auto","int","relative","fraction","array"],"strings":[],"default":"()","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"rows","details":[{"kind":"html","content":"The row sizes. See the grid documentation for more\ninformation on track sizing.
"}],"types":["auto","int","relative","fraction","array"],"strings":[],"default":"()","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"gutter","details":[{"kind":"html","content":"The gaps between rows and columns. This is a shorthand for setting\ncolumn-gutter and row-gutter to the same value. See the grid\ndocumentation for more information on gutters.
()","positional":false,"named":true,"required":false,"variadic":false,"settable":false},{"name":"column-gutter","details":[{"kind":"html","content":"The gaps between columns. Takes precedence over gutter. See the\ngrid documentation for more information on gutters.
()","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"row-gutter","details":[{"kind":"html","content":"The gaps between rows. Takes precedence over gutter. See the\ngrid documentation for more information on gutters.
()","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"inset","details":[{"kind":"html","content":"How much to pad the cells' content.
\nTo specify the same inset for all cells, use a single length for all\nsides, or a dictionary of lengths for individual sides. See the\nbox's documentation for more details.
\nTo specify a varying inset for different cells, you can:
\nSee the grid documentation for more details.
"},{"kind":"example","content":{"body":"#table(\n columns: 2,\n inset: 10pt,\n [Hello],\n [World],\n)\n\n#table(\n columns: 2,\n inset: (x: 20pt, y: 10pt),\n [Hello],\n [World],\n)\n![\"Preview\"](\"/en-US-v0.14.1/assets/cd5db0284b844bb717f37c7ea3a5989c.png\")
0% + 5pt","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"align","details":[{"kind":"html","content":"How to align the cells' content.
\nIf set to auto, the outer alignment is used.
You can specify the alignment in any of the following fashions:
\nSee the Table Guide for details.
"},{"kind":"example","content":{"body":"#table(\n columns: 3,\n align: (left, center, right),\n [Hello], [Hello], [Hello],\n [A], [B], [C],\n)\n![\"Preview\"](\"/en-US-v0.14.1/assets/fdf060a2d0a5f8bb558ef194e322452d.png\")
auto","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"fill","details":[{"kind":"html","content":"How to fill the cells.
\nThis can be:
\nMost notably, arrays and functions are useful for creating striped\ntables. See the Table Guide for more\ndetails.
"},{"kind":"example","content":{"body":"#table(\n fill: (x, _) =>\n if calc.odd(x) { luma(240) }\n else { white },\n align: (x, y) =>\n if y == 0 { center }\n else if x == 0 { left }\n else { right },\n columns: 4,\n [], [*Q1*], [*Q2*], [*Q3*],\n [Revenue:], [1000 €], [2000 €], [3000 €],\n [Expenses:], [500 €], [1000 €], [1500 €],\n [Profit:], [500 €], [1000 €], [1500 €],\n)\n![\"Preview\"](\"/en-US-v0.14.1/assets/1ce6e13c91ef624898a870a344ad491f.png\")
none","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"stroke","details":[{"kind":"html","content":"How to stroke the cells.
\nStrokes can be disabled by setting this to none.
If it is necessary to place lines which can cross spacing between cells\nproduced by the gutter option, or to override the\nstroke between multiple specific cells, consider specifying one or more\nof table.hline and table.vline alongside your table cells.
To specify the same stroke for all cells, use a single stroke for all\nsides, or a dictionary of strokes for individual sides. See\nthe rectangle's documentation for more details.
\nTo specify varying strokes for different cells, you can:
\nSee the Table Guide for more details.
"}],"types":["none","length","color","gradient","array","stroke","tiling","dictionary","function"],"strings":[],"default":"1pt + black","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"children","details":[{"kind":"html","content":"The contents of the table cells, plus any extra table lines specified\nwith the table.hline and table.vline elements.
A cell in the table. Use this to position a cell manually or to apply\nstyling. To do the latter, you can either use the function to override the\nproperties for a particular cell, or use it in show rules to apply certain\nstyles to multiple cells at once.
\nPerhaps the most important use case of table.cell is to make a cell span\nmultiple columns and/or rows with the colspan and rowspan fields.
#show table.cell.where(y: 0): strong\n#set table(\n stroke: (x, y) => if y == 0 {\n (bottom: 0.7pt + black)\n },\n align: (x, y) => (\n if x > 0 { center }\n else { left }\n )\n)\n\n#table(\n columns: 3,\n table.header(\n [Substance],\n [Subcritical °C],\n [Supercritical °C],\n ),\n [Hydrochloric Acid],\n [12.0], [92.1],\n [Sodium Myreth Sulfate],\n [16.6], [104],\n [Potassium Hydroxide],\n table.cell(colspan: 2)[24.7],\n)\n![\"Preview\"](\"/en-US-v0.14.1/assets/dab40f9bc81b4706c5aa22132650faa0.png\")
For example, you can override the fill, alignment or inset for a single\ncell:
"},{"kind":"example","content":{"body":"// You can also import those.\n#import table: cell, header\n\n#table(\n columns: 2,\n align: center,\n header(\n [*Trip progress*],\n [*Itinerary*],\n ),\n cell(\n align: right,\n fill: fuchsia.lighten(80%),\n [🚗],\n ),\n [Get in, folks!],\n [🚗], [Eat curbside hotdog],\n cell(align: left)[🌴🚗],\n cell(\n inset: 0.06em,\n text(1.62em)[🏝️🌅🌊],\n ),\n)\n![\"Preview\"](\"/en-US-v0.14.1/assets/2e8ea263e8c68ccb5299513a02c8a043.png\")
You may also apply a show rule on table.cell to style all cells at once.\nCombined with selectors, this allows you to apply styles based on a cell's\nposition:
#show table.cell.where(x: 0): strong\n\n#table(\n columns: 3,\n gutter: 3pt,\n [Name], [Age], [Strength],\n [Hannes], [36], [Grace],\n [Irma], [50], [Resourcefulness],\n [Vikram], [49], [Perseverance],\n)\n![\"Preview\"](\"/en-US-v0.14.1/assets/73648fd3af6abcc0737856eb8d5b3ca7.png\")
The cell's body.
"}],"types":["content"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":false,"settable":false},{"name":"x","details":[{"kind":"html","content":"The cell's column (zero-indexed).\nFunctions identically to the x field in grid.cell.
auto","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"y","details":[{"kind":"html","content":"The cell's row (zero-indexed).\nFunctions identically to the y field in grid.cell.
auto","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"colspan","details":[{"kind":"html","content":"The amount of columns spanned by this cell.
"}],"types":["int"],"strings":[],"default":"1","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"rowspan","details":[{"kind":"html","content":"The amount of rows spanned by this cell.
"}],"types":["int"],"strings":[],"default":"1","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"inset","details":[{"kind":"html","content":"The cell's inset override.
"}],"types":["auto","relative","dictionary"],"strings":[],"default":"auto","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"align","details":[{"kind":"html","content":"The cell's alignment override.
"}],"types":["auto","alignment"],"strings":[],"default":"auto","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"fill","details":[{"kind":"html","content":"The cell's fill override.
"}],"types":["none","auto","color","gradient","tiling"],"strings":[],"default":"auto","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"stroke","details":[{"kind":"html","content":"The cell's stroke override.
"}],"types":["none","length","color","gradient","stroke","tiling","dictionary"],"strings":[],"default":"(:)","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"breakable","details":[{"kind":"html","content":"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.
auto","positional":false,"named":true,"required":false,"variadic":false,"settable":true}],"returns":["content"],"scope":[]},{"path":["table"],"name":"hline","title":"Table Horizontal Line","keywords":[],"oneliner":"A horizontal line in the table.","element":true,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"A horizontal line in the table.
\nOverrides any per-cell stroke, including stroke specified through the\ntable's stroke field. Can cross spacing between cells created through the\ntable's column-gutter option.
Use this function instead of the table's stroke field if you want to\nmanually place a horizontal line at a specific position in a single table.\nConsider using table's stroke field or table.cell's\nstroke field instead if the line you want to place is\npart of all your tables' designs.
#set table.hline(stroke: .6pt)\n\n#table(\n stroke: none,\n columns: (auto, 1fr),\n [09:00], [Badge pick up],\n [09:45], [Opening Keynote],\n [10:30], [Talk: Typst's Future],\n [11:15], [Session: Good PRs],\n table.hline(start: 1),\n [Noon], [_Lunch break_],\n table.hline(start: 1),\n [14:00], [Talk: Tracked Layout],\n [15:00], [Talk: Automations],\n [16:00], [Workshop: Tables],\n table.hline(),\n [19:00], [Day 1 Attendee Mixer],\n)\n![\"Preview\"](\"/en-US-v0.14.1/assets/165f96ef6c21f2194a6fbd988e52743e.png\")
The row above which the horizontal line is placed (zero-indexed).\nFunctions identically to the y field in grid.hline.
auto","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"start","details":[{"kind":"html","content":"The column at which the horizontal line starts (zero-indexed, inclusive).
"}],"types":["int"],"strings":[],"default":"0","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"end","details":[{"kind":"html","content":"The column before which the horizontal line ends (zero-indexed,\nexclusive).
"}],"types":["none","int"],"strings":[],"default":"none","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"stroke","details":[{"kind":"html","content":"The line's stroke.
\nSpecifying none removes any lines previously placed across this\nline's range, including hlines or per-cell stroke below it.
1pt + black","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"position","details":[{"kind":"html","content":"The position at which the line is placed, given its row (y) - either\ntop to draw above it or bottom to draw below it.
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.
top","positional":false,"named":true,"required":false,"variadic":false,"settable":true}],"returns":["content"],"scope":[]},{"path":["table"],"name":"vline","title":"Table Vertical Line","keywords":[],"oneliner":"A vertical line in the table.","element":true,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"A vertical line in the table. See the docs for grid.vline for more\ninformation regarding how to use this element's fields.
Overrides any per-cell stroke, including stroke specified through the\ntable's stroke field. Can cross spacing between cells created through the\ntable's row-gutter option.
Similar to table.hline, use this function if you want to manually place\na vertical line at a specific position in a single table and use the\ntable's stroke field or table.cell's\nstroke field instead if the line you want to place is\npart of all your tables' designs.
The column before which the vertical line is placed (zero-indexed).\nFunctions identically to the x field in grid.vline.
auto","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"start","details":[{"kind":"html","content":"The row at which the vertical line starts (zero-indexed, inclusive).
"}],"types":["int"],"strings":[],"default":"0","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"end","details":[{"kind":"html","content":"The row on top of which the vertical line ends (zero-indexed,\nexclusive).
"}],"types":["none","int"],"strings":[],"default":"none","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"stroke","details":[{"kind":"html","content":"The line's stroke.
\nSpecifying none removes any lines previously placed across this\nline's range, including vlines or per-cell stroke below it.
1pt + black","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"position","details":[{"kind":"html","content":"The position at which the line is placed, given its column (x) -\neither start to draw before it or end to draw after it.
The values left and right are also accepted, but discouraged as\nthey cause your table to be inconsistent between left-to-right and\nright-to-left documents.
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.
start","positional":false,"named":true,"required":false,"variadic":false,"settable":true}],"returns":["content"],"scope":[]},{"path":["table"],"name":"header","title":"Table Header","keywords":[],"oneliner":"A repeatable table header.","element":true,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"A repeatable table header.
\nYou should wrap your tables' heading rows in this function even if you do\nnot plan to wrap your table across pages because Typst uses this function to\nattach accessibility metadata to tables and ensure Universal\nAccess to your document.
\nYou can use the repeat parameter to control whether your table's header\nwill be repeated across pages.
Currently, this function is unsuitable for creating a header column or\nsingle header cells. Either use regular cells, or, if you are exporting a\nPDF, you can also use the pdf.header-cell function to mark a cell as a\nheader cell. Likewise, you can use pdf.data-cell to mark cells in this\nfunction as data cells. Note that these functions are not final and thus\nonly available when you enable the a11y-extras feature (see the PDF\nmodule documentation for details).
#set page(height: 11.5em)\n#set table(\n fill: (x, y) =>\n if x == 0 or y == 0 {\n gray.lighten(40%)\n },\n align: right,\n)\n\n#show table.cell.where(x: 0): strong\n#show table.cell.where(y: 0): strong\n\n#table(\n columns: 4,\n table.header(\n [], [Blue chip],\n [Fresh IPO], [Penny st'k],\n ),\n table.cell(\n rowspan: 6,\n align: horizon,\n rotate(-90deg, reflow: true)[\n *USD / day*\n ],\n ),\n [0.20], [104], [5],\n [3.17], [108], [4],\n [1.59], [84], [1],\n [0.26], [98], [15],\n [0.01], [195], [4],\n [7.34], [57], [2],\n)\n![\"Preview](\"/en-US-v0.14.1/assets/207a73a7e6fb990edcb409654b11167d-0.png\")
![\"Preview](\"/en-US-v0.14.1/assets/207a73a7e6fb990edcb409654b11167d-1.png\")
Whether this header should be repeated across pages.
"}],"types":["bool"],"strings":[],"default":"true","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"level","details":[{"kind":"html","content":"The level of the header. Must not be zero.
\nThis allows repeating multiple headers at once. Headers with different\nlevels can repeat together, as long as they have ascending levels.
\nNotably, when a header with a lower level starts repeating, all higher\nor equal level headers stop repeating (they are "replaced" by the new\nheader).
"}],"types":["int"],"strings":[],"default":"1","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"children","details":[{"kind":"html","content":"The cells and lines within the header.
"}],"types":["content"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":true,"settable":false}],"returns":["content"],"scope":[]},{"path":["table"],"name":"footer","title":"Table Footer","keywords":[],"oneliner":"A repeatable table footer.","element":true,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"A repeatable table footer.
\nJust like the table.header element, the footer can repeat itself on\nevery page of the table. This is useful for improving legibility by adding\nthe column labels in both the header and footer of a large table, totals, or\nother information that should be visible on every page.
No other table cells may be placed after the footer.
"}],"self":false,"params":[{"name":"repeat","details":[{"kind":"html","content":"Whether this footer should be repeated across pages.
"}],"types":["bool"],"strings":[],"default":"true","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"children","details":[{"kind":"html","content":"The cells and lines within the footer.
"}],"types":["content"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":true,"settable":false}],"returns":["content"],"scope":[]}]}}}