{"route":"/en-US-v0.13.1/guides/table-guide/","title":"Table guide","description":"Not sure how to change table strokes? Need to rotate a table? This guide\nexplains all you need to know about tables in Typst.\n","part":null,"outline":[{"id":"basic-tables","name":"Basic Tables","children":[]},{"id":"column-sizes","name":"Column Sizes","children":[]},{"id":"captions-and-references","name":"Captions And References","children":[]},{"id":"fills","name":"Fills","children":[{"id":"fill-override","name":"Fill Override","children":[]}]},{"id":"strokes","name":"Strokes","children":[{"id":"individual-lines","name":"Individual Lines","children":[]},{"id":"stroke-override","name":"Stroke Override","children":[]},{"id":"stroke-functions","name":"Stroke Functions","children":[]},{"id":"double-stroke","name":"Double Stroke","children":[]}]},{"id":"alignment","name":"Alignment","children":[]},{"id":"merge-cells","name":"Merge Cells","children":[]},{"id":"rotate-table","name":"Rotate Table","children":[]},{"id":"table-across-pages","name":"Table Across Pages","children":[]},{"id":"importing-data","name":"Importing Data","children":[]},{"id":"table-and-grid","name":"Table And Grid","children":[]}],"body":{"kind":"html","content":"

Table guide

\n

Tables are a great way to present data to your readers in an easily readable,\ncompact, and organized manner. They are not only used for numerical values, but\nalso survey responses, task planning, schedules, and more. Because of this wide\nset of possible applications, there is no single best way to lay out a table.\nInstead, think about the data you want to highlight, your document's overarching\ndesign, and ultimately how your table can best serve your readers.

\n

Typst can help you with your tables by automating styling, importing data from\nother applications, and more! This guide takes you through a few of the most\ncommon questions you may have when adding a table to your document with Typst.\nFeel free to skip to the section most relevant to you – we designed this guide\nto be read out of order.

\n

If you want to look up a detail of how tables work, you should also check out\ntheir reference page. And if you are looking for a table of contents\nrather than a normal table, the reference page of the outline\nfunction is the right place to learn more.

\n

How to create a basic table?

\n

In order to create a table in Typst, use the table function. For a\nbasic table, you need to tell the table function two things:

\n\n

So, let's say you want to create a table with two columns describing the\ningredients for a cookie recipe:

\n
#table(\n  columns: 2,\n  [*Amount*], [*Ingredient*],\n  [360g], [Baking flour],\n  [250g], [Butter (room temp.)],\n  [150g], [Brown sugar],\n  [100g], [Cane sugar],\n  [100g], [70% cocoa chocolate],\n  [100g], [35-40% cocoa chocolate],\n  [2], [Eggs],\n  [Pinch], [Salt],\n  [Drizzle], [Vanilla extract],\n)\n
\"Preview\"
\n

This example shows how to call, configure, and populate a table. Both the column\ncount and cell contents are passed to the table as arguments. The argument\nlist is surrounded by round parentheses. In it, we first pass the\ncolumn count as a named argument. Then, we pass multiple content\nblocks as positional arguments. Each content block contains the\ncontents for a single cell.

\n

To make the example more legible, we have placed two content block arguments on\neach line, mimicking how they would appear in the table. You could also write\neach cell on its own line. Typst does not care on which line you place the\narguments. Instead, Typst will place the content cells from left to right (or\nright to left, if that is the writing direction of your language) and then from\ntop to bottom. It will automatically add enough rows to your table so that it\nfits all of your content.

\n

It is best to wrap the header row of your table in the table.header\nfunction. This clarifies your intent and will also allow future\nversions of Typst to make the output more accessible to users with a screen\nreader:

\n
#table(\n  columns: 2,\n  table.header[*Amount*][*Ingredient*],\n  [360g], [Baking flour],\n // ... the remaining cells\n)\n
\"Preview\"
\n

You could also write a show rule that automatically strongly\nemphasizes the contents of the first cells for all tables. This\nquickly becomes useful if your document contains multiple tables!

\n
#show table.cell.where(y: 0): strong\n\n#table(\n  columns: 2,\n  table.header[Amount][Ingredient],\n  [360g], [Baking flour],\n // ... the remaining cells\n)\n
\"Preview\"
\n

We are using a show rule with a selector for cell coordinates here instead of\napplying our styles directly to table.header. This is due to a current\nlimitation of Typst that will be fixed in a future release.

\n

Congratulations, you have created your first table! Now you can proceed to\nchange column sizes, adjust the strokes, add\nstriped rows, and more!

\n

How to change the column sizes?

\n

If you create a table and specify the number of columns, Typst will make each\ncolumn large enough to fit its largest cell. Often, you want something\ndifferent, for example, to make a table span the whole width of the page. You\ncan provide a list, specifying how wide you want each column to be, through the\ncolumns argument. There are a few different ways to specify column widths:

\n\n

Let's put this to use with a table that contains the dates, numbers, and\ndescriptions of some routine checks. The first two columns are auto-sized and\nthe last column is 1fr wide as to fill the whole page.

\n
#table(\n  columns: (auto, auto, 1fr),\n  table.header[Date][°No][Description],\n  [24/01/03], [813], [Filtered participant pool],\n  [24/01/03], [477], [Transitioned to sec. regimen],\n  [24/01/11], [051], [Cycled treatment substrate],\n)\n
\"Preview\"
\n

Here, we have passed our list of column lengths as an array, enclosed in round\nparentheses, with its elements separated by commas. The first two columns are\nautomatically sized, so that they take on the size of their content and the\nthird column is sized as 1fr so that it fills up the remainder of the space\non the page. If you wanted to instead change the second column to be a bit more\nspacious, you could replace its entry in the columns array with a value like\n6em.

\n

How to caption and reference my table?

\n

A table is just as valuable as the information your readers draw from it. You\ncan enhance the effectiveness of both your prose and your table by making a\nclear connection between the two with a cross-reference. Typst can help you with\nautomatic references and the figure function.

\n

Just like with images, wrapping a table in the figure function allows you to\nadd a caption and a label, so you can reference the figure elsewhere. Wrapping\nyour table in a figure also lets you use the figure's placement parameter to\nfloat it to the top or bottom of a page.

\n

Let's take a look at a captioned table and how to reference it in prose:

\n
#show table.cell.where(y: 0): set text(weight: "bold")\n\n#figure(\n  table(\n    columns: 4,\n    stroke: none,\n\n    table.header[Test Item][Specification][Test Result][Compliance],\n    [Voltage], [220V ± 5%], [218V], [Pass],\n    [Current], [5A ± 0.5A], [4.2A], [Fail],\n  ),\n  caption: [Probe results for design A],\n) <probe-a>\n\nThe results from @probe-a show that the design is not yet optimal.\nWe will show how its performance can be improved in this section.\n
\"Preview\"
\n

The example shows how to wrap a table in a figure, set a caption and a label,\nand how to reference that label. We start by using the figure function. It\nexpects the contents of the figure as a positional argument. We just put the\ntable function call in its argument list, omitting the # character because it\nis only needed when calling a function in markup mode. We also add the caption\nas a named argument (above or below) the table.

\n

After the figure call, we put a label in angle brackets (<probe-a>). This\ntells Typst to remember this element and make it referenceable under this name\nthroughout your document. We can then reference it in prose by using the at sign\nand the label name @probe-a. Typst will print a nicely formatted reference\nand automatically update the label if the table's number changes.

\n

How to get a striped table?

\n

Many tables use striped rows or columns instead of strokes to differentiate\nbetween rows and columns. This effect is often called zebra stripes. Tables\nwith zebra stripes are popular in Business and commercial Data Analytics\napplications, while academic applications tend to use strokes instead.

\n

To add zebra stripes to a table, we use the table function's fill argument.\nIt can take three kinds of arguments:

\n\n

Let's start with an example of a horizontally striped table:

\n
#set text(font: "IBM Plex Sans")\n\n// Medium bold table header.\n#show table.cell.where(y: 0): set text(weight: "medium")\n\n// Bold titles.\n#show table.cell.where(x: 1): set text(weight: "bold")\n\n// See the strokes section for details on this!\n#let frame(stroke) = (x, y) => (\n  left: if x > 0 { 0pt } else { stroke },\n  right: stroke,\n  top: if y < 2 { stroke } else { 0pt },\n  bottom: stroke,\n)\n\n#set table(\n  fill: (rgb("EAF2F5"), none),\n  stroke: frame(rgb("21222C")),\n)\n\n#table(\n  columns: (0.4fr, 1fr, 1fr, 1fr),\n\n  table.header[Month][Title][Author][Genre],\n  [January], [The Great Gatsby], [F. Scott Fitzgerald], [Classic],\n  [February], [To Kill a Mockingbird], [Harper Lee], [Drama],\n  [March], [1984], [George Orwell], [Dystopian],\n  [April], [The Catcher in the Rye], [J.D. Salinger], [Coming-of-Age],\n)\n
\"Preview\"
\n

This example shows a book club reading list. The line fill: (rgb("EAF2F5"), none) in table's set rule is all that is needed to add striped columns. It\ntells Typst to alternate between coloring columns with a light blue (in the\nrgb function call) and nothing (none). Note that we\nextracted all of our styling from the table function call itself into set and\nshow rules, so that we can automatically reuse it for multiple tables.

\n

Because setting the stripes itself is easy we also added some other styles to\nmake it look nice. The other code in the example provides a dark blue\nstroke around the table and below the first line and\nemboldens the first row and the column with the book title. See the\nstrokes section for details on how we achieved this stroke\nconfiguration.

\n

Let's next take a look at how we can change only the set rule to achieve\nhorizontal stripes instead:

\n
#set table(\n  fill: (_, y) => if calc.odd(y) { rgb("EAF2F5") },\n  stroke: frame(rgb("21222C")),\n)\n
\"Preview\"
\n

We just need to replace the set rule from the previous example with this one and\nget horizontal stripes instead. Here, we are passing a function to fill. It\ndiscards the horizontal coordinate with an underscore and then checks if the\nvertical coordinate y of the cell is odd. If so, the cell gets a light blue\nfill, otherwise, no fill is returned.

\n

Of course, you can make this function arbitrarily complex. For example, if you\nwant to stripe the rows with a light and darker shade of blue, you could do\nsomething like this:

\n
#set table(\n  fill: (_, y) => (none, rgb("EAF2F5"), rgb("DDEAEF")).at(calc.rem(y, 3)),\n  stroke: frame(rgb("21222C")),\n)\n
\"Preview\"
\n

This example shows an alternative approach to write our fill function. The\nfunction uses an array with three colors and then cycles between its values for\neach row by indexing the array with the remainder of y divided by 3.

\n

Finally, here is a bonus example that uses the stroke to achieve striped rows:

\n
#set table(\n  stroke: (x, y) => (\n    y: 1pt,\n    left: if x > 0 { 0pt } else if calc.even(y) { 1pt },\n    right: if calc.even(y) { 1pt },\n  ),\n)\n
\"Preview\"
\n

Manually overriding a cell's fill color

\n

Sometimes, the fill of a cell needs not to vary based on its position in the\ntable, but rather based on its contents. We can use the table.cell\nelement in the table's parameter list to wrap a cell's content\nand override its fill.

\n

For example, here is a list of all German presidents, with the cell borders\ncolored in the color of their party.

\n
#set text(font: "Roboto")\n\n#let cdu(name) = ([CDU], table.cell(fill: black, text(fill: white, name)))\n#let spd(name) = ([SPD], table.cell(fill: red, text(fill: white, name)))\n#let fdp(name) = ([FDP], table.cell(fill: yellow, name))\n\n#table(\n  columns: (auto, auto, 1fr),\n  stroke: (x: none),\n\n  table.header[Tenure][Party][President],\n  [1949-1959], ..fdp[Theodor Heuss],\n  [1959-1969], ..cdu[Heinrich Lübke],\n  [1969-1974], ..spd[Gustav Heinemann],\n  [1974-1979], ..fdp[Walter Scheel],\n  [1979-1984], ..cdu[Karl Carstens],\n  [1984-1994], ..cdu[Richard von Weizsäcker],\n  [1994-1999], ..cdu[Roman Herzog],\n  [1999-2004], ..spd[Johannes Rau],\n  [2004-2010], ..cdu[Horst Köhler],\n  [2010-2012], ..cdu[Christian Wulff],\n  [2012-2017], [n/a], [Joachim Gauck],\n  [2017-],     ..spd[Frank-Walter-Steinmeier],\n)\n
\"Preview\"
\n

In this example, we make use of variables because there only have been a total\nof three parties whose members have become president (and one unaffiliated\npresident). Their colors will repeat multiple times, so we store a function that\nproduces an array with their party's name and a table cell with that party's\ncolor and the president's name (cdu, spd, and fdp). We then use these\nfunctions in the table argument list instead of directly adding the name. We\nuse the spread operator .. to turn the items of the\narrays into single cells. We could also write something like\n[FDP], table.cell(fill: yellow)[Theodor Heuss] for each cell directly in the\ntable's argument list, but that becomes unreadable, especially for the parties\nwhose colors are dark so that they require white text. We also delete vertical\nstrokes and set the font to Roboto.

\n

The party column and the cell color in this example communicate redundant\ninformation on purpose: Communicating important data using color only is a bad\naccessibility practice. It disadvantages users with vision impairment and is in\nviolation of universal access standards, such as the\nWCAG 2.1 Success Criterion 1.4.1.\nTo improve this table, we added a column printing the party name. Alternatively,\nyou could have made sure to choose a color-blindness friendly palette and mark\nup your cells with an additional label that screen readers can read out loud.\nThe latter feature is not currently supported by Typst, but will be added in a\nfuture release. You can check how colors look for color-blind readers with\nthis Chrome extension,\nPhotoshop, or\nGIMP.

\n

How to adjust the lines in a table?

\n

By default, Typst adds strokes between each row and column of a table. You can\nadjust these strokes in a variety of ways. Which one is the most practical,\ndepends on the modification you want to make and your intent:

\n\n

We will go over all of these options with examples next! First, we will tackle\nthe table function's stroke argument. Here, you can adjust\nboth how the table's lines get drawn and configure which lines are drawn at all.

\n

Let's start by modifying the color and thickness of the stroke:

\n
#table(\n  columns: 4,\n  stroke: 0.5pt + rgb("666675"),\n  [*Monday*], [11.5], [13.0], [4.0],\n  [*Tuesday*], [8.0], [14.5], [5.0],\n  [*Wednesday*], [9.0], [18.5], [13.0],\n)\n
\"Preview\"
\n

This makes the table lines a bit less wide and uses a bluish gray. You can see\nthat we added a width in point to a color to achieve our customized stroke. This\naddition yields a value of the stroke type. Alternatively, you can\nuse the dictionary representation for strokes which allows you to access\nadvanced features such as dashed lines.

\n

The previous example showed how to use the stroke argument in the table\nfunction's invocation. Alternatively, you can specify the stroke argument in the\ntable's set rule. This will have exactly the same effect on all subsequent\ntable calls as if the stroke argument was specified in the argument list. This\nis useful if you are writing a template or want to style your whole document.

\n
// Renders the exact same as the last example\n#set table(stroke: 0.5pt + rgb("666675"))\n\n#table(\n  columns: 4,\n  [*Monday*], [11.5], [13.0], [4.0],\n  [*Tuesday*], [8.0], [14.5], [5.0],\n  [*Wednesday*], [9.0], [18.5], [13.0],\n)\n
\n

For small tables, you sometimes want to suppress all strokes because they add\ntoo much visual noise. To do this, just set the stroke argument to none:

\n
#table(\n  columns: 4,\n  stroke: none,\n  [*Monday*], [11.5], [13.0], [4.0],\n  [*Tuesday*], [8.0], [14.5], [5.0],\n  [*Wednesday*], [9.0], [18.5], [13.0],\n)\n
\"Preview\"
\n

If you want more fine-grained control of where lines get placed in your table,\nyou can also pass a dictionary with the keys top, left, right, bottom\n(controlling the respective cell sides), x, y (controlling vertical and\nhorizontal strokes), and rest (covers all strokes not styled by other\ndictionary entries). All keys are optional; omitted keys will be treated as if\ntheir value was the default value. For example, to get a table with only\nhorizontal lines, you can do this:

\n
#table(\n  columns: 2,\n  stroke: (x: none),\n  align: horizon,\n  [☒], [Close cabin door],\n  [☐], [Start engines],\n  [☐], [Radio tower],\n  [☐], [Push back],\n)\n
\"Preview\"
\n

This turns off all vertical strokes and leaves the horizontal strokes in place.\nTo achieve the reverse effect (only horizontal strokes), set the stroke argument\nto (y: none) instead.

\n

Further down in the guide, we cover how to use a function\nin the stroke argument to customize all strokes individually. This is how you\nachieve more complex stroking patterns.

\n

Adding individual lines in the table

\n

If you want to add a single horizontal or vertical line in your table, for\nexample to separate a group of rows, you can use the table.hline and\ntable.vline elements for horizontal and vertical lines, respectively. Add\nthem to the argument list of the table function just like you would add\nindividual cells and a header.

\n

Let's take a look at the following example from the reference:

\n
#set table.hline(stroke: 0.6pt)\n\n#table(\n  stroke: none,\n  columns: (auto, 1fr),\n  // Morning schedule abridged.\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\"
\n

In this example, you can see that we have placed a call to table.hline between\nthe cells, producing a horizontal line at that spot. We also used a set rule on\nthe element to reduce its stroke width to make it fit better with the weight of\nthe font.

\n

By default, Typst places horizontal and vertical lines after the current row or\ncolumn, depending on their position in the argument list. You can also manually\nmove them to a different position by adding the y (for hline) or x (for\nvline) argument. For example, the code below would produce the same result:

\n
#set table.hline(stroke: 0.6pt)\n\n#table(\n  stroke: none,\n  columns: (auto, 1fr),\n  // Morning schedule abridged.\n  table.hline(y: 3),\n  [14:00], [Talk: Tracked Layout],\n  [15:00], [Talk: Automations],\n  [16:00], [Workshop: Tables],\n  [19:00], [Day 1 Attendee Mixer],\n)\n
\n

Let's imagine you are working with a template that shows none of the table\nstrokes except for one between the first and second row. Now, since you have one\ntable that also has labels in the first column, you want to add an extra\nvertical line to it. However, you do not want this vertical line to cross into\nthe top row. You can achieve this with the start argument:

\n
// Base template already configured tables, but we need some\n// extra configuration for this table.\n#{\n  set table(align: (x, _) => if x == 0 { left } else { right })\n  show table.cell.where(x: 0): smallcaps\n  table(\n    columns: (auto, 1fr, 1fr, 1fr),\n    table.vline(x: 1, start: 1),\n    table.header[Trainset][Top Speed][Length][Weight],\n    [TGV Réseau], [320 km/h], [200m], [383t],\n    [ICE 403], [330 km/h], [201m], [409t],\n    [Shinkansen N700], [300 km/h], [405m], [700t],\n  )\n}\n
\"Preview\"
\n

In this example, we have added table.vline at the start of our positional\nargument list. But because the line is not supposed to go to the left of the\nfirst column, we specified the x argument as 1. We also set the start\nargument to 1 so that the line does only start after the first row.

\n

The example also contains two more things: We use the align argument with a\nfunction to right-align the data in all but the first column and use a show rule\nto make the first column of table cells appear in small capitals. Because these\nstyles are specific to this one table, we put everything into a code\nblock, so that the styling does not affect any further\ntables.

\n

Overriding the strokes of a single cell

\n

Imagine you want to change the stroke around a single cell. Maybe your cell is\nvery important and needs highlighting! For this scenario, there is the\ntable.cell function. Instead of adding your content directly in\nthe argument list of the table, you wrap it in a table.cell call. Now, you can\nuse table.cell's argument list to override the table properties, such as the\nstroke, for this cell only.

\n

Here's an example with a matrix of two of the Big Five personality factors, with\none intersection highlighted.

\n
#table(\n  columns: 3,\n  stroke: (x: none),\n\n  [], [*High Neuroticism*], [*Low Neuroticism*],\n\n  [*High Agreeableness*],\n  table.cell(stroke: orange + 2pt)[\n    _Sensitive_ \\ Prone to emotional distress but very empathetic.\n  ],\n  [_Compassionate_ \\ Caring and stable, often seen as a supportive figure.],\n\n  [*Low Agreeableness*],\n  [_Contentious_ \\ Competitive and easily agitated.],\n  [_Detached_ \\ Independent and calm, may appear aloof.],\n)\n
\"Preview\"
\n

Above, you can see that we used the table.cell element in the table's argument\nlist and passed the cell content to it. We have used its stroke argument to\nset a wider orange stroke. Despite the fact that we disabled vertical strokes on\nthe table, the orange stroke appeared on all sides of the modified cell, showing\nthat the table's stroke configuration is overwritten.

\n

Complex document-wide stroke customization

\n

This section explains how to customize all lines at once in one or multiple\ntables. This allows you to draw only the first horizontal line or omit the outer\nlines, without knowing how many cells the table has. This is achieved by\nproviding a function to the table's stroke parameter. The function should\nreturn a stroke given the zero-indexed x and y position of the current cell. You\nshould only need these functions if you are a template author, do not use a\ntemplate, or need to heavily customize your tables. Otherwise, your template\nshould set appropriate default table strokes.

\n

For example, this is a set rule that draws all horizontal lines except for the\nvery first and last line.

\n
#show table.cell.where(x: 0): set text(style: "italic")\n#show table.cell.where(y: 0): set text(style: "normal", weight: "bold")\n#set table(stroke: (_, y) => if y > 0 { (top: 0.8pt) })\n\n#table(\n  columns: 3,\n  align: center + horizon,\n  table.header[Technique][Advantage][Drawback],\n  [Diegetic], [Immersive], [May be contrived],\n  [Extradiegetic], [Breaks immersion], [Obtrusive],\n  [Omitted], [Fosters engagement], [May fracture audience],\n)\n
\"Preview\"
\n

In the set rule, we pass a function that receives two arguments, assigning the\nvertical coordinate to y and discarding the horizontal coordinate. It then\nreturns a stroke dictionary with a 0.8pt top stroke for all but the first\nline. The cells in the first line instead implicitly receive none as the\nreturn value. You can easily modify this function to just draw the inner\nvertical lines instead as (x, _) => if x > 0 { (left: 0.8pt) }.

\n

Let's try a few more stroking functions. The next function will only draw a line\nbelow the first row:

\n
#set table(stroke: (_, y) => if y == 0 { (bottom: 1pt) })\n\n// Table as seen above\n
\"Preview\"
\n

If you understood the first example, it becomes obvious what happens here. We\ncheck if we are in the first row. If so, we return a bottom stroke. Otherwise,\nwe'll return none implicitly.

\n

The next example shows how to draw all but the outer lines:

\n
#set table(stroke: (x, y) => (\n  left: if x > 0 { 0.8pt },\n  top: if y > 0 { 0.8pt },\n))\n\n// Table as seen above\n
\"Preview\"
\n

This example uses both the x and y coordinates. It omits the left stroke in\nthe first column and the top stroke in the first row. The right and bottom lines\nare not drawn.

\n

Finally, here is a table that draws all lines except for the vertical lines in\nthe first row and horizontal lines in the table body. It looks a bit like a\ncalendar.

\n
#set table(stroke: (x, y) => (\n  left: if x == 0 or y > 0 { 1pt } else { 0pt },\n  right: 1pt,\n  top: if y <= 1 { 1pt } else { 0pt },\n  bottom: 1pt,\n))\n\n// Table as seen above\n
\"Preview\"
\n

This example is a bit more complex. We start by drawing all the strokes on the\nright of the cells. But this means that we have drawn strokes in the top row,\ntoo, and we don't need those! We use the fact that left will override right\nand only draw the left line if we are not in the first row or if we are in the\nfirst column. In all other cases, we explicitly remove the left line. Finally,\nwe draw the horizontal lines by first setting the bottom line and then for the\nfirst two rows with the top key, suppressing all other top lines. The last\nline appears because there is no top line that could suppress it.

\n

How to achieve a double line?

\n

Typst does not yet have a native way to draw double strokes, but there are\nmultiple ways to emulate them, for example with tilings. We will\nshow a different workaround in this section: Table gutters.

\n

Tables can space their cells apart using the gutter argument. When a gutter is\napplied, a stroke is drawn on each of the now separated cells. We can\nselectively add gutter between the rows or columns for which we want to draw a\ndouble line. The row-gutter and column-gutter arguments allow us to do this.\nThey accept arrays of gutter values. Let's take a look at an example:

\n
#table(\n  columns: 3,\n  stroke: (x: none),\n  row-gutter: (2.2pt, auto),\n  table.header[Date][Exercise Type][Calories Burned],\n  [2023-03-15], [Swimming], [400],\n  [2023-03-17], [Weightlifting], [250],\n  [2023-03-18], [Yoga], [200],\n)\n
\"Preview\"
\n

We can see that we used an array for row-gutter that specifies a 2.2pt gap\nbetween the first and second row. It then continues with auto (which is the\ndefault, in this case 0pt gutter) which will be the gutter between all other\nrows, since it is the last entry in the array.

\n

How to align the contents of the cells in my table?

\n

You can use multiple mechanisms to align the content in your table. You can\neither use the table function's align argument to set the alignment for your\nwhole table (or use it in a set rule to set the alignment for tables throughout\nyour document) or the align function (or table.cell's align argument) to\noverride the alignment of a single cell.

\n

When using the table function's align argument, you can choose between three\nmethods to specify an alignment:

\n\n

For example, this travel itinerary right-aligns the day column and left-aligns\neverything else by providing an array in the align argument:

\n
#set text(font: "IBM Plex Sans")\n#show table.cell.where(y: 0): set text(weight: "bold")\n\n#table(\n  columns: 4,\n  align: (right, left, left, left),\n  fill: (_, y) => if calc.odd(y) { green.lighten(90%) },\n  stroke: none,\n\n  table.header[Day][Location][Hotel or Apartment][Activities],\n  [1], [Paris, France], [Hôtel de l'Europe], [Arrival, Evening River Cruise],\n  [2], [Paris, France], [Hôtel de l'Europe], [Louvre Museum, Eiffel Tower],\n  [3], [Lyon, France], [Lyon City Hotel], [City Tour, Local Cuisine Tasting],\n  [4], [Geneva, Switzerland], [Lakeview Inn], [Lake Geneva, Red Cross Museum],\n  [5], [Zermatt, Switzerland], [Alpine Lodge], [Visit Matterhorn, Skiing],\n)\n
\"Preview\"
\n

However, this example does not yet look perfect — the header cells should be\nbottom-aligned. Let's use a function instead to do so:

\n
#set text(font: "IBM Plex Sans")\n#show table.cell.where(y: 0): set text(weight: "bold")\n\n#table(\n  columns: 4,\n  align: (x, y) =>\n    if x == 0 { right } else { left } +\n    if y == 0 { bottom } else { top },\n  fill: (_, y) => if calc.odd(y) { green.lighten(90%) },\n  stroke: none,\n\n  table.header[Day][Location][Hotel or Apartment][Activities],\n  [1], [Paris, France], [Hôtel de l'Europe], [Arrival, Evening River Cruise],\n  [2], [Paris, France], [Hôtel de l'Europe], [Louvre Museum, Eiffel Tower],\n // ... remaining days omitted\n)\n
\"Preview\"
\n

In the function, we calculate a horizontal and vertical alignment based on\nwhether we are in the first column (x == 0) or the first row (y == 0).\nWe then make use of the fact that we can add horizontal and vertical alignments\nwith + to receive a single, two-dimensional alignment.

\n

You can find an example of using table.cell to change a single cell's\nalignment on its reference page.

\n

How to merge cells?

\n

When a table contains logical groupings or the same data in multiple adjacent\ncells, merging multiple cells into a single, larger cell can be advantageous.\nAnother use case for cell groups are table headers with multiple rows: That way,\nyou can group for example a sales data table by quarter in the first row and by\nmonths in the second row.

\n

A merged cell spans multiple rows and/or columns. You can achieve it with the\ntable.cell function's rowspan and colspan arguments: Just specify how\nmany rows or columns you want your cell to span.

\n

The example below contains an attendance calendar for an office with in-person\nand remote days for each team member. To make the table more glanceable, we\nmerge adjacent cells with the same value:

\n
#let ofi = [Office]\n#let rem = [_Remote_]\n#let lea = [*On leave*]\n\n#show table.cell.where(y: 0): set text(\n  fill: white,\n  weight: "bold",\n)\n\n#table(\n  columns: 6 * (1fr,),\n  align: (x, y) => if x == 0 or y == 0 { left } else { center },\n  stroke: (x, y) => (\n    // Separate black cells with white strokes.\n    left: if y == 0 and x > 0 { white } else { black },\n    rest: black,\n  ),\n  fill: (_, y) => if y == 0 { black },\n\n  table.header(\n    [Team member],\n    [Monday],\n    [Tuesday],\n    [Wednesday],\n    [Thursday],\n    [Friday]\n  ),\n  [Evelyn Archer],\n    table.cell(colspan: 2, ofi),\n    table.cell(colspan: 2, rem),\n    ofi,\n  [Lila Montgomery],\n    table.cell(colspan: 5, lea),\n  [Nolan Pearce],\n    rem,\n    table.cell(colspan: 2, ofi),\n    rem,\n    ofi,\n)\n
\"Preview\"
\n

In the example, we first define variables with "Office", "Remote", and "On\nleave" so we don't have to write these labels out every time. We can then use\nthese variables in the table body either directly or in a table.cell call if\nthe team member spends multiple consecutive days in office, remote, or on leave.

\n

The example also contains a black header (created with table's fill\nargument) with white strokes (table's stroke argument) and white text (set\nby the table.cell set rule). Finally, we align all the content of all table\ncells in the body in the center. If you want to know more about the functions\npassed to align, stroke, and fill, you can check out the sections on\nalignment, strokes, and striped\ntables.

\n

This table would be a great candidate for fully automated generation from an\nexternal data source! Check out the section about importing\ndata to learn more about that.

\n

How to rotate a table?

\n

When tables have many columns, a portrait paper orientation can quickly get\ncramped. Hence, you'll sometimes want to switch your tables to landscape\norientation. There are two ways to accomplish this in Typst:

\n\n

Below, we will demonstrate both techniques with a student grade book table.

\n

First, we will rotate the table on the page. The example also places some text\non the right of the table.

\n
#set page("a5", columns: 2, numbering: "— 1 —")\n#show table.cell.where(y: 0): set text(weight: "bold")\n\n#rotate(\n  -90deg,\n  reflow: true,\n\n  table(\n    columns: (1fr,) + 5 * (auto,),\n    inset: (x: 0.6em,),\n    stroke: (_, y) => (\n      x: 1pt,\n      top: if y <= 1 { 1pt } else { 0pt },\n      bottom: 1pt,\n    ),\n    align: (left, right, right, right, right, left),\n\n    table.header(\n      [Student Name],\n      [Assignment 1], [Assignment 2],\n      [Mid-term], [Final Exam],\n      [Total Grade],\n    ),\n    [Jane Smith], [78%], [82%], [75%], [80%], [B],\n    [Alex Johnson], [90%], [95%], [94%], [96%], [A+],\n    [John Doe], [85%], [90%], [88%], [92%], [A],\n    [Maria Garcia], [88%], [84%], [89%], [85%], [B+],\n    [Zhang Wei], [93%], [89%], [90%], [91%], [A-],\n    [Marina Musterfrau], [96%], [91%], [74%], [69%], [B-],\n  ),\n)\n\n#lorem(80)\n
\"Preview\"
\n

What we have here is a two-column document on ISO A5 paper with page numbers on\nthe bottom. The table has six columns and contains a few customizations to\nstroke, alignment and spacing. But the most important part is that\nthe table is wrapped in a call to the rotate function with the reflow\nargument being true. This will make the table rotate 90 degrees\ncounterclockwise. The reflow argument is needed so that the table's rotation\naffects the layout. If it was omitted, Typst would lay out the page as if the\ntable was not rotated (true might become the default in the future).

\n

The example also shows how to produce many columns of the same size: To the\ninitial 1fr column, we add an array with five auto items that we\ncreate by multiplying an array with one auto item by five. Note that arrays\nwith just one item need a trailing comma to distinguish them from merely\nparenthesized expressions.

\n

The second example shows how to rotate the whole page, so that the table stays\nupright:

\n
#set page("a5", numbering: "— 1 —")\n#show table.cell.where(y: 0): set text(weight: "bold")\n\n#page(flipped: true)[\n  #table(\n    columns: (1fr,) + 5 * (auto,),\n    inset: (x: 0.6em,),\n    stroke: (_, y) => (\n      x: 1pt,\n      top: if y <= 1 { 1pt } else { 0pt },\n      bottom: 1pt,\n    ),\n    align: (left, right, right, right, right, left),\n\n    table.header(\n      [Student Name],\n      [Assignment 1], [Assignment 2],\n      [Mid-term], [Final Exam],\n      [Total Grade],\n    ),\n    [Jane Smith], [78%], [82%], [75%], [80%], [B],\n    [Alex Johnson], [90%], [95%], [94%], [96%], [A+],\n    [John Doe], [85%], [90%], [88%], [92%], [A],\n    [Maria Garcia], [88%], [84%], [89%], [85%], [B+],\n    [Zhang Wei], [93%], [89%], [90%], [91%], [A-],\n    [Marina Musterfrau], [96%], [91%], [74%], [69%], [B-],\n  )\n\n  #pad(x: 15%, top: 1.5em)[\n    = Winter 2023/24 results\n    #lorem(80)\n  ]\n]\n
\"Preview\"
\n

Here, we take the same table and the other content we want to set with it and\nput it into a call to the page function while supplying true to the\nflipped argument. This will instruct Typst to create new pages with width and\nheight swapped and place the contents of the function call onto a new page.\nNotice how the page number is also on the long edge of the paper now. At the\nbottom of the page, we use the pad function to constrain the width of the\nparagraph to achieve a nice and legible line length.

\n

How to break a table across pages?

\n

It is best to contain a table on a single page. However, some tables just have\nmany rows, so breaking them across pages becomes unavoidable. Fortunately, Typst\nsupports breaking tables across pages out of the box. If you are using the\ntable.header and table.footer functions, their contents will be repeated\non each page as the first and last rows, respectively. If you want to disable\nthis behavior, you can set repeat to false on either of them.

\n

If you have placed your table inside of a figure, it becomes unable to break\nacross pages by default. However, you can change this behavior. Let's take a\nlook:

\n
#set page(width: 9cm, height: 6cm)\n#show table.cell.where(y: 0): set text(weight: "bold")\n#show figure: set block(breakable: true)\n\n#figure(\n  caption: [Training regimen for Marathon],\n  table(\n    columns: 3,\n    fill: (_, y) => if y == 0 { gray.lighten(75%) },\n\n    table.header[Week][Distance (km)][Time (hh:mm:ss)],\n    [1], [5],  [00:30:00],\n    [2], [7],  [00:45:00],\n    [3], [10], [01:00:00],\n    [4], [12], [01:10:00],\n    [5], [15], [01:25:00],\n    [6], [18], [01:40:00],\n    [7], [20], [01:50:00],\n    [8], [22], [02:00:00],\n    [...], [...], [...],\n    table.footer[_Goal_][_42.195_][_02:45:00_],\n  )\n)\n
\"Preview\"
\n

A figure automatically produces a block which cannot break by default.\nHowever, we can reconfigure the block of the figure using a show rule to make it\nbreakable. Now, the figure spans multiple pages with the headers and footers\nrepeating.

\n

How to import data into a table?

\n

Often, you need to put data that you obtained elsewhere into a table. Sometimes,\nthis is from Microsoft Excel or Google Sheets, sometimes it is from a dataset\non the web or from your experiment. Fortunately, Typst can load many common\nfile formats, so you can use scripting to include their\ndata in a table.

\n

The most common file format for tabular data is CSV. You can obtain a CSV file\nfrom Excel by choosing "Save as" in the File menu and choosing the file format\n"CSV UTF-8 (Comma-delimited) (.csv)". Save the file and, if you are using the\nweb app, upload it to your project.

\n

In our case, we will be building a table about Moore's Law. For this purpose, we\nare using a statistic with how many transistors the average microprocessor\nconsists of per year from Our World in\nData. Let's\nstart by pressing the "Download" button to get a CSV file with the raw data.

\n

Be sure to move the file to your project or somewhere Typst can see it, if you\nare using the CLI. Once you did that, we can open the file to see how it is\nstructured:

\n
\nEntity,Code,Year,Transistors per microprocessor\nWorld,OWID_WRL,1971,2308.2417\nWorld,OWID_WRL,1972,3554.5222\nWorld,OWID_WRL,1974,6097.5625\n
\n

The file starts with a header and contains four columns: Entity (which is to\nwhom the metric applies), Code, the year, and the number of transistors per\nmicroprocessor. Only the last two columns change between each row, so we can\ndisregard "Entity" and "Code".

\n

First, let's start by loading this file with the csv function. It accepts\nthe file name of the file we want to load as a string argument:

\n
#let moore = csv("moore.csv")\n
\n

We have loaded our file (assuming we named it moore.csv) and bound\nit to the new variable moore. This will not produce any\noutput, so there's nothing to see yet. If we want to examine what Typst loaded,\nwe can either hover the name of the variable in the web app or print some items\nfrom the array:

\n
#let moore = csv("moore.csv")\n\n#moore.slice(0, 3)\n
\"Preview\"
\n

With the arguments (0, 3), the slice method returns the\nfirst three items in the array (with the indices 0, 1, and 2). We can see that\neach row is its own array with one item per cell.

\n

Now, let's write a loop that will transform this data into an array of cells\nthat we can use with the table function.

\n
#let moore = csv("moore.csv")\n\n#table(\n  columns: 2,\n  ..for (.., year, count) in moore {\n    (year, count)\n  }\n)\n
\"Preview\"
\n

The example above uses a for loop that iterates over the rows in our CSV file\nand returns an array for each iteration. We use the for loop's\ndestructuring capability to discard all but the last two\nitems of each row. We then create a new array with just these two. Because Typst\nwill concatenate the array results of all the loop iterations, we get a\none-dimensional array in which the year column and the number of transistors\nalternate. We can then insert the array as cells. For this we use the spread\noperator (..). By prefixing an array, or, in our case\nan expression that yields an array, with two dots, we tell Typst that the\narray's items should be used as positional arguments.

\n

Alternatively, we can also use the map, slice,\nand flatten array methods to write this in a more functional\nstyle:

\n
#let moore = csv("moore.csv")\n\n#table(\n   columns: moore.first().len(),\n   ..moore.map(m => m.slice(2)).flatten(),\n)\n
\n

This example renders the same as the previous one, but first uses the map\nfunction to change each row of the data. We pass a function to map that gets run\non each row of the CSV and returns a new value to replace that row with. We use\nit to discard the first two columns with slice. Then, we spread the data into\nthe table function. However, we need to pass a one-dimensional array and\nmoore's value is two-dimensional (that means that each of its row values\ncontains an array with the cell data). That's why we call flatten which\nconverts it to a one-dimensional array. We also extract the number of columns\nfrom the data itself.

\n

Now that we have nice code for our table, we should try to also make the table\nitself nice! The transistor counts go from millions in 1995 to trillions in 2021\nand changes are difficult to see with so many digits. We could try to present\nour data logarithmically to make it more digestible:

\n
#let moore = csv("moore.csv")\n#let moore-log = moore.slice(1).map(m => {\n  let (.., year, count) = m\n  let log = calc.log(float(count))\n  let rounded = str(calc.round(log, digits: 2))\n  (year, rounded)\n})\n\n#show table.cell.where(x: 0): strong\n\n#table(\n   columns: moore-log.first().len(),\n   align: right,\n   fill: (_, y) => if calc.odd(y) { rgb("D7D9E0") },\n   stroke: none,\n\n   table.header[Year][Transistor count ($log_10$)],\n   table.hline(stroke: rgb("4D4C5B")),\n   ..moore-log.flatten(),\n)\n
\"Preview\"
\n

In this example, we first drop the header row from the data since we are adding\nour own. Then, we discard all but the last two columns as above. We do this by\ndestructuring the array m, discarding all but the two\nlast items. We then convert the string in count to a floating point number,\ncalculate its logarithm and store it in the variable log. Finally, we round it\nto two digits, convert it to a string, and store it in the variable rounded.\nThen, we return an array with year and rounded that replaces the original\nrow. In our table, we have added our custom header that tells the reader that\nwe've applied a logarithm to the values. Then, we spread the flattened data as\nabove.

\n

We also styled the table with stripes, a\nhorizontal line below the first row, aligned\neverything to the right, and emboldened the first column. Click on the links to\ngo to the relevant guide sections and see how it's done!

\n

What if I need the table function for something that isn't a table?

\n

Tabular layouts of content can be useful not only for matrices of closely\nrelated data, like shown in the examples throughout this guide, but also for\npresentational purposes. Typst differentiates between grids that are for layout\nand presentational purposes only and tables, in which the arrangement of the\ncells itself conveys information.

\n

To make this difference clear to other software and allow templates to heavily\nstyle tables, Typst has two functions for grid and table layout:

\n\n

Both elements work the same way and have the same arguments. You can apply\neverything you have learned about tables in this guide to grids. There are only\nthree differences:

\n"}}