Semantic layouts

The contents below link to each definition. Function entries show the signature, then a description, then the parameters with their types and defaults; variable entries show the declared type.

Creates a validated author record for setup(authors:) and layouts.title(authors:).

author(
  name,
  affiliations: (),
  email: none,
  orcid: none,
  corresponding: false
) -> dictionary

A name on its own needs no record at all. authors: takes content or a string wherever it takes a record, so authors: [Ada Lovelace] and authors: ([Ada Lovelace], [Charles Babbage]) are both complete author lists. Reach for author() when a name carries more than itself:

#let ada = mosaic.layouts.author(
  [Ada Lovelace],
  affiliations: ([Analytical Society], [University of London]),
  email: "ada@example.org",
  orcid: "0000-0002-1825-0097",
  corresponding: true,
)

Affiliations

An affiliation is the institution itself: content or a non-empty string. Two authors share one legend number exactly when they give the same affiliation, so bind a shared institution once and reuse the binding:

#let lon = [University of London]
#let ada = mosaic.layouts.author([Ada Lovelace], affiliations: (lon,))
#let bab = mosaic.layouts.author([Charles Babbage], affiliations: (lon,))

The academic title variant renders these as superscript numbers over a numbered legend. Compact variants list them without numbering.

Validation

Values are checked at construction rather than at render time:

• email must look like an address.
• orcid must be a well-formed iD.
• corresponding requires at least one of email or orcid.

Creates a conventional header, body, and footer grid recipe.

content(variant: "header-body-footer", columns: 1, tracks: auto) -> dictionary

This is the ordinary slide layout, and the one automatic level-two headings resolve to. It builds a vertical Mosaic split whose body child is a horizontal split of plain cells.

#mosaic.slide(
  layout: mosaic.layouts.content(variant: "header-body", columns: 2),
  [== Two columns],
  [Left body],
  [Right body],
)

Cells

The surrounding mosaic.slide fills cells in traversal order:

• header, when the variant includes one.
• body, or body-1, body-2, and so on when columns is above one.
• footer, when the variant includes one.

A setup-level content: (footer: ...) default can satisfy the footer, so a positional slide may omit that final block.

Variants

• body: one region, edge to edge.
• header-body: a content-sized header above the body.
• body-footer: the body above a content-sized footer.
• header-body-footer: both. The default.

Labels

Every resolved cell carries a label, so appearance comes from native Typst rules:

• mosaic-cell-header: the header, in the variants that include one.
• mosaic-cell-body: the body, when columns is one.
• mosaic-cell-body-1, mosaic-cell-body-2, and so on: the body columns, when columns is above one.
• mosaic-cell-footer: the footer, in the variants that include one.

Styling

The layout is purely structural, so its looks come from rules on those labels.

#show label("mosaic-cell-header"): set block(fill: luma(240))

The header cell carries no special typography of its own. Put a native level-two heading in its content to style it as a heading and register it with outlines.

mosaic.layouts.content(columns: 2, tracks: (2fr, 1fr))

Creates an image-first grid recipe.

image(
  image,
  variant: "figure",
  caption: none,
  fit: auto,
  tracks: auto
) -> dictionary

This is the image-first counterpart to layouts.content: the picture is the argument rather than slide content, and the text regions arrange around it. The surrounding mosaic.slide fills only the text cells.

#mosaic.slide(
  layout: mosaic.layouts.image(
    path("chart.webp"),
    caption: [Revenue by quarter],
  ),
  [== Results],
)

Variants

• figure: a contained picture centered under a header cell, with an optional caption below it. The conventional academic figure slide, and the default.
• left, right, top, bottom: a full-bleed picture paired with a text region of header and body cells, sized by tracks.
• full: the picture behind a single body cell, so text reads over the photograph. Put a heading inside the body to title it, or pass an empty block for a bare full-bleed slide.

Captions

A caption composes a native Typst figure around the picture, so it takes the deck’s own show figure.caption styling and figure numbering. Switch the numbering off with an ordinary set figure(numbering: none). Captions are accepted by the figure variant only.

Labels

Every resolved cell carries a label, so appearance comes from native Typst rules:

• mosaic-cell-header: the header, in the figure and directional variants.
• mosaic-cell-body: the text region, in the directional and full variants.
• mosaic-cell-image: the picture, in the figure and directional variants. The full variant paints the picture as the body cell’s background instead, so it has no image cell of its own.

Styling

The layout is purely structural, so its looks come from rules on those labels. The full variant inherits the surrounding native text color, so quiet the photograph with the image dictionary’s scrim key and override the cell’s text fill.

#show label("mosaic-cell-body"): set text(fill: white)
#mosaic.slide(
  layout: mosaic.layouts.image(
    (path: "photo.webp", scrim: black.transparentize(55%)),
    variant: "full",
  ),
  [== Full bleed],
)

Creates a presentation title grid.

title(
  title: auto,
  subtitle: auto,
  date: auto,
  image: none,
  variant: "ruled",
  position: auto,
  authors: auto,
  tracks: auto,
  rule: auto,
  accent: auto
) -> dictionary

The layout supplies every cell’s content itself, so the surrounding mosaic.slide consumes no slide bodies.

#show: mosaic.setup.with(
  title: [Tree-based slide grids],
  subtitle: [A layout model for Typst],
  authors: [Ada Lovelace],
  date: [2026-08-03],
)

#mosaic.slide(layout: "title", variant: "centered")

Inheritance

Each of title, subtitle, authors, and date defaults to auto, which takes the value configured on setup. To override an inherited value:

• Pass explicit content or a string to replace it.
• Pass none to suppress an inherited title, subtitle, or date.
• Pass () to suppress inherited authors.

Variants

Text variants:

• centered: the heading stack at the slide’s center, details anchored to the bottom edge.
• bordered: a thin rule border inset from the slide edge with the centered stack inside it.
• ruled: the heading stack over a full-width accent rule with the details beneath, flush left at the slide’s vertical center. The beamer-metropolis title page, and the default.
• kicker: the magazine masthead. A strong opening rule, the subtitle set as a small tracked-caps eyebrow in the accent color, the title below it, and the details anchored to the bottom edge.
• panel: a vertical side panel in the deck’s text color carries the details, knocked out in the canvas color under a short accent rule; the heading stack takes the main field.
• academic: the conference-poster arrangement. Author names carry superscript affiliation numbers over a numbered affiliation legend and a contact line. Requires at least one author.

One image variant, which requires image and reads position:

• image with position: "left", "right", "top", or "bottom" (the default is "left"): a full-bleed picture beside or above the title stack, sized by tracks.

A full-slide photographic title is not a variant: give the slide a background: plane and compose the type yourself, reading the deck’s own metadata back through info().

To invert any of these, with the slide ground in the deck’s text color and the type knocked out, pass invert: true on the slide rather than picking a variant; inversion is a polarity, not a structure.

Authors

Every variant accepts the same authors, written in whichever of three spellings fits the deck: one name as content or a string, an array of names, or an array of records built with layouts.author for the authors that carry affiliations, an ORCID iD, or an address. Names and records mix freely in one array. Every variant renders every author field through the same tiers: a byline of names with linked ORCID labels, superscript affiliation numbers, and the corresponding asterisk, then one fine-print line per kind of information: the numbered affiliation legend, the contact addresses, the date. Kinds never share a line, and the superscript markers appear exactly when the deck names more than one institution.

Labels

Every resolved cell carries a label, so appearance comes from native Typst rules:

• mosaic-cell-title: the title stack, in every variant. Most variants compose the subtitle and the details inside it too.
• mosaic-cell-details: the affiliation and date band, in the panel and academic variants, which set those tiers outside the title cell.
• mosaic-cell-authors: the byline, in the academic variant.
• mosaic-cell-image: the picture, in the image variant.

One further label is not a cell: the display line of the title stack carries mosaic-title-display, which is where a theme states the title’s display size.

Styling

The layout is structural. A rule on <mosaic-cell-title> reaches the whole composed stack: title, subtitle, and details alike. Recoloring it is what light-on-dark compositions over a photograph need.

#show label("mosaic-cell-title"): set text(fill: white)
#mosaic.slide(
  layout: "title",
  background: mosaic.components.image("cover.webp", scrim: black.transparentize(55%)),
)

Sizing it works the same way, because the display line carries its own <mosaic-title-display> label and the theme’s display size lands there rather than on the cell. The tiers below are ordinary ems of the cell, so one rule scales the stack as a unit and the proportions hold. That is how to ask for quiet type in the corner of a photograph.

#show label("mosaic-cell-title"): set text(size: 0.45em)

A theme states the display size on the inner label instead, which leaves the outer one free for the deck to scale:

#show label("mosaic-title-display"): set text(size: 2em, weight: "semibold")

Creates a section divider grid.

section(
  subtitle: none,
  number: none,
  image: none,
  variant: "plain",
  accent: auto,
  tracks: auto
) -> dictionary

The section cell’s text is the slide’s own content, so the surrounding mosaic.slide supplies one block. Automatic level-one headings resolve to this layout.

#mosaic.slide(
  layout: "section",
  number: [02],
  subtitle: [How the grid resolves],
)[Structure]

Variants

• plain: one centered section cell. The default.
• rule: a heavy full-width rule with the title hanging beneath it, flush left, the number above the rule.
• numeral: the section number set enormous in the line color, bleeding off the top-right edge behind a lower-left title stack.
• baseline: title flush left and number flush right sharing one baseline, tied together by a full-width hairline.
• toc: every section in the deck listed, the current one alive with its number, the others ghosted.
• image-left, image-right, image-top, image-bottom: that cell beside or above a full-bleed image cell, sized by tracks.
• image-background: the section text directly over a full-slide picture.

Every image variant requires image. The designed text variants (every variant but plain and the image ones) treat an omitted number as the automatic section counter, so they need no argument in the ordinary case.

Labels

Every resolved cell carries a label, so appearance comes from native Typst rules:

• mosaic-cell-section: the section text, in every variant. The number and subtitle are composed inside it, so one rule reaches the whole stack.
• mosaic-cell-image: the picture, in the directional image variants. The image-background variant paints the picture as the section cell’s background instead, so it has no image cell of its own.

Styling

The layout is structural. The centered arrangement and title typography come from the <mosaic-cell-section> label rules setup emits. Over a photograph the text inherits the surrounding native text color, so quiet the picture with the image dictionary’s scrim key and override the cell’s text fill.

#show label("mosaic-cell-section"): set text(fill: white)
#mosaic.slide(
  layout: "section",
  variant: "image-background",
  image: (path: "cover.webp", scrim: black.transparentize(55%)),
)[Structure]