Struct TableElem

pub struct TableElem {
    pub children: Vec<TableChild>,
    /* private fields */
}

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, Typst will annotate its output in the future such that screenreaders will announce content in table as tabular while a grid’s content will be announced no different than multiple content blocks in the document flow.

Note that, to override a particular cell’s properties or apply show rules on table cells, you can use the table.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.

To give a table a caption and make it referenceable, put it into a [figure].

Example

The example below demonstrates some of the most common table options.

#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 to customize the appearance and the position of each cell.

>>> #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,
)

Fields

children: Vec<TableChild>

Implementations

impl TableElem

pub fn new(children: Vec<TableChild>) -> Self

Create a new instance of the element.

pub fn with_columns(self, columns: TrackSizings) -> Self

Builder-style setter for the columns field.

pub fn with_rows(self, rows: TrackSizings) -> Self

Builder-style setter for the rows field.

pub fn with_column_gutter(self, column_gutter: TrackSizings) -> Self

Builder-style setter for the column-gutter field.

pub fn with_row_gutter(self, row_gutter: TrackSizings) -> Self

Builder-style setter for the row-gutter field.

pub fn with_fill(self, fill: Celled<Option<Paint>>) -> Self

Builder-style setter for the fill field.

pub fn with_align(self, align: Celled<Smart<Alignment>>) -> Self

Builder-style setter for the align field.

pub fn with_stroke( self, stroke: Celled<Sides<Option<Option<Arc<Stroke>>>>>, ) -> Self

Builder-style setter for the stroke field.

pub fn with_inset(self, inset: Celled<Sides<Option<Rel<Length>>>>) -> Self

Builder-style setter for the inset field.

pub fn push_columns(&mut self, columns: TrackSizings)

Setter for the columns field.

pub fn push_rows(&mut self, rows: TrackSizings)

Setter for the rows field.

pub fn push_column_gutter(&mut self, column_gutter: TrackSizings)

Setter for the column-gutter field.

pub fn push_row_gutter(&mut self, row_gutter: TrackSizings)

Setter for the row-gutter field.

pub fn push_fill(&mut self, fill: Celled<Option<Paint>>)

Setter for the fill field.

pub fn push_align(&mut self, align: Celled<Smart<Alignment>>)

Setter for the align field.

pub fn push_stroke( &mut self, stroke: Celled<Sides<Option<Option<Arc<Stroke>>>>>, )

Setter for the stroke field.

pub fn push_inset(&mut self, inset: Celled<Sides<Option<Rel<Length>>>>)

Setter for the inset field.

pub fn columns<'a>(&'a self, styles: StyleChain<'a>) -> &'a TrackSizings

The column sizes. See the grid documentation for more information on track sizing.

pub fn rows<'a>(&'a self, styles: StyleChain<'a>) -> &'a TrackSizings

The row sizes. See the grid documentation for more information on track sizing.

pub fn column_gutter<'a>(&'a self, styles: StyleChain<'a>) -> &'a TrackSizings

The gaps between columns. Takes precedence over gutter. See the grid documentation for more information on gutters.

pub fn row_gutter<'a>(&'a self, styles: StyleChain<'a>) -> &'a TrackSizings

The gaps between rows. Takes precedence over gutter. See the grid documentation for more information on gutters.

pub fn fill<'a>(&'a self, styles: StyleChain<'a>) -> &'a Celled<Option<Paint>>

How to fill the cells.

This can be a color or a function that returns a color. The function receives the cells’ column and row indices, starting from zero. This can be used to implement striped tables.

#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 €],
)

pub fn align<'a>( &'a self, styles: StyleChain<'a>, ) -> &'a Celled<Smart<Alignment>>

How to align the cells’ content.

This can either be a single alignment, an array of alignments (corresponding to each column) or a function that returns an alignment. The function receives the cells’ column and row indices, starting from zero. If set to {auto}, the outer alignment is used.

#table(
  columns: 3,
  align: (left, center, right),
  [Hello], [Hello], [Hello],
  [A], [B], [C],
)

pub fn stroke( &self, styles: StyleChain<'_>, ) -> <Celled<Sides<Option<Option<Arc<Stroke>>>>> as Resolve>::Output

How to [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 option, or to override the stroke between multiple specific cells, consider specifying one or more of table.hline and table.vline alongside your table cells.

See the grid documentation for more information on strokes.

pub fn inset( &self, styles: StyleChain<'_>, ) -> Celled<Sides<Option<Rel<Length>>>>

How much to pad the cells’ content.

#table(
  inset: 10pt,
  [Hello],
  [World],
)

#table(
  columns: 2,
  inset: (
    x: 20pt,
    y: 10pt,
  ),
  [Hello],
  [World],
)

pub fn columns_in(styles: StyleChain<'_>) -> &TrackSizings

Access the columns field in the given style chain.

pub fn rows_in(styles: StyleChain<'_>) -> &TrackSizings

Access the rows field in the given style chain.

pub fn column_gutter_in(styles: StyleChain<'_>) -> &TrackSizings

Access the column-gutter field in the given style chain.

pub fn row_gutter_in(styles: StyleChain<'_>) -> &TrackSizings

Access the row-gutter field in the given style chain.

pub fn fill_in(styles: StyleChain<'_>) -> &Celled<Option<Paint>>

Access the fill field in the given style chain.

pub fn align_in(styles: StyleChain<'_>) -> &Celled<Smart<Alignment>>

Access the align field in the given style chain.

pub fn stroke_in( styles: StyleChain<'_>, ) -> <Celled<Sides<Option<Option<Arc<Stroke>>>>> as Resolve>::Output

Access the stroke field in the given style chain.

pub fn inset_in(styles: StyleChain<'_>) -> Celled<Sides<Option<Rel<Length>>>>

Access the inset field in the given style chain.

pub fn set_columns(columns: TrackSizings) -> Property

Create a style property for the columns field.

pub fn set_rows(rows: TrackSizings) -> Property

Create a style property for the rows field.

pub fn set_column_gutter(column_gutter: TrackSizings) -> Property

Create a style property for the column-gutter field.

pub fn set_row_gutter(row_gutter: TrackSizings) -> Property

Create a style property for the row-gutter field.

pub fn set_fill(fill: Celled<Option<Paint>>) -> Property

Create a style property for the fill field.

pub fn set_align(align: Celled<Smart<Alignment>>) -> Property

Create a style property for the align field.

pub fn set_stroke( stroke: Celled<Sides<Option<Option<Arc<Stroke>>>>>, ) -> Property

Create a style property for the stroke field.

pub fn set_inset(inset: Celled<Sides<Option<Rel<Length>>>>) -> Property

Create a style property for the inset field.

Trait Implementations

impl Capable for TableElem

fn vtable(capability: TypeId) -> Option<NonNull<()>>

Get the pointer to the vtable for the given capability / trait.

impl Clone for TableElem

fn clone(&self) -> TableElem

Returns a duplicate of the value.

const fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Construct for TableElem

fn construct(engine: &mut Engine<'_>, args: &mut Args) -> SourceResult<Content>

Construct an element from the arguments.

impl Debug for TableElem

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Fields for TableElem

type Enum = Fields

An enum with the fields of the element.

fn has(&self, id: u8) -> bool

Whether the element has the given field set.

fn field(&self, id: u8) -> Result<Value, FieldAccessError>

Get the field with the given field ID.

fn field_with_styles( &self, id: u8, styles: StyleChain<'_>, ) -> Result<Value, FieldAccessError>

Get the field with the given ID in the presence of styles.

fn field_from_styles( id: u8, styles: StyleChain<'_>, ) -> Result<Value, FieldAccessError>

Get the field with the given ID from the styles.

fn materialize(&mut self, styles: StyleChain<'_>)

Resolve all fields with the styles and save them in-place.

fn fields(&self) -> Dict

Get the fields of the element.

impl Hash for TableElem

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl IntoValue for TableElem

fn into_value(self) -> Value

Cast this type into a value.

impl NativeElement for TableElem

fn data() -> &'static NativeElementData

Get the element data for the native Rust element.

fn elem() -> Element

where Self: Sized,

Get the element for the native Rust element.

fn pack(self) -> Content

where Self: Sized,

Pack the element into type-erased content.

impl NativeScope for TableElem

fn constructor() -> Option<&'static NativeFuncData>

The constructor function for the type, if any.

fn scope() -> Scope

Get the associated scope for the type.

impl PartialEq for TableElem

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

const fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Repr for TableElem

fn repr(&self) -> EcoString

Return the debug representation of the value.

impl Set for TableElem

fn set(engine: &mut Engine<'_>, args: &mut Args) -> SourceResult<Styles>

Parse relevant arguments into style properties for this element.