Struct GridElem

pub struct GridElem {
    pub children: Vec<GridChild>,
    /* private fields */
}

Arranges content in a grid.

The grid element allows you to arrange content in a grid. You can define the number of rows and columns, as well as the size of the gutters between them. There are multiple sizing modes for columns and rows that can be used to create complex layouts.

While the grid and table elements work very similarly, they are intended for different use cases and carry different semantics. The grid element is intended for presentational and layout purposes, while the {table} element is intended for, in broad terms, presenting multiple related data points. In the future, Typst will annotate its output 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. Set and show rules on one of these elements do not affect the other.

A grid’s sizing is determined by the track sizes specified in the arguments. Because each of the sizing parameters accepts the same values, we will explain them just once, here. Each sizing argument accepts an array of individual track sizes. A track size is either:

• {auto}: The track will be sized to fit its contents. It will be at most as large as the remaining space. If there is more than one {auto} track width, and together they claim more than the available space, the {auto} tracks will fairly distribute the available space among themselves.

• A fixed or relative length (e.g. {10pt} or {20% - 1cm}): The track will be exactly of this size.

• A fractional length (e.g. {1fr}): Once all other tracks have been sized, the remaining space will be divided among the fractional tracks according to their fractions. For example, if there are two fractional tracks, each with a fraction of {1fr}, they will each take up half of the remaining space.

To specify a single track, the array can be omitted in favor of a single value. To specify multiple {auto} tracks, enter the number of tracks instead of an array. For example, columns: {3} is equivalent to columns: {(auto, auto, auto)}.

Examples

The example below demonstrates the different track sizing options. It also shows how you can use grid.cell to make an individual cell span two grid tracks.

// We use `rect` to emphasize the
// area of cells.
#set rect(
  inset: 8pt,
  fill: rgb("e4e5ea"),
  width: 100%,
)

#grid(
  columns: (60pt, 1fr, 2fr),
  rows: (auto, 60pt),
  gutter: 3pt,
  rect[Fixed width, auto height],
  rect[1/3 of the remains],
  rect[2/3 of the remains],
  rect(height: 100%)[Fixed height],
  grid.cell(
    colspan: 2,
    image("tiger.jpg", width: 100%),
  ),
)

You can also spread an array of strings or content into a grid to populate its cells.

#grid(
  columns: 5,
  gutter: 5pt,
  ..range(25).map(str)
)

Styling the grid

The grid’s appearance can be customized through different parameters. These are the most important ones:

• fill to give all cells a background
• align to change how cells are aligned
• inset to optionally add internal padding to each cell
• stroke to optionally enable grid lines with a certain stroke

If you need to override one of the above options for a single cell, you can use the grid.cell element. Likewise, you can override individual grid lines with the grid.hline and grid.vline elements.

Alternatively, if you need the appearance options to depend on a cell’s position (column and row), you may specify a function to fill or align of the form (column, row) => value. You may also use a show rule on grid.cell - see that element’s examples or the examples below for more information.

Locating most of your styling in set and show rules is recommended, as it keeps the grid’s or table’s actual usages clean and easy to read. It also allows you to easily change the grid’s appearance in one place.

Stroke styling precedence

There are three ways to set the stroke of a grid cell: through {grid.cell}’s stroke field, by using {grid.hline} and {grid.vline}, or by setting the {grid}’s stroke field. When multiple of these settings are present and conflict, the hline and vline settings take the highest precedence, followed by the cell settings, and finally the grid settings.

Furthermore, strokes of a repeated grid header or footer will take precedence over regular cell strokes.

Fields

children: Vec<GridChild>

Implementations

impl GridElem

pub fn new(children: Vec<GridChild>) -> 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.

Either specify a track size array or provide an integer to create a grid with that many {auto}-sized columns. Note that opposed to rows and gutters, providing a single track size will only ever create a single column.

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

The row sizes.

If there are more cells than fit the defined rows, the last row is repeated until there are no more cells.

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

The gaps between columns.

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

The gaps between rows.

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 grids.

#grid(
  fill: (x, y) =>
    if calc.even(x + y) { luma(230) }
    else { white },
  align: center + horizon,
  columns: 4,
  inset: 2pt,
  [X], [O], [X], [O],
  [O], [X], [O], [X],
  [X], [O], [X], [O],
  [O], [X], [O], [X],
)

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.

You can find an example for this argument at the table.align parameter.

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

How to stroke the cells.

Grids have no strokes by default, which can be changed by setting this option to the desired stroke.

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 grid.hline and grid.vline alongside your grid cells.

#set page(height: 13em, width: 26em)

#let cv(..jobs) = grid(
  columns: 2,
  inset: 5pt,
  stroke: (x, y) => if x == 0 and y > 0 {
    (right: (
      paint: luma(180),
      thickness: 1.5pt,
      dash: "dotted"
    ))
  },
  grid.header(grid.cell(colspan: 2)[
    *Professional Experience*
    #box(width: 1fr, line(length: 100%, stroke: luma(180)))
  ]),
  ..{
    let last = none
    for job in jobs.pos() {
      (
        if job.year != last [*#job.year*],
        [
          *#job.company* - #job.role _(#job.timeframe)_ \
          #job.details
        ]
      )
      last = job.year
    }
  }
)

#cv(
  (
    year: 2012,
    company: [Pear Seed & Co.],
    role: [Lead Engineer],
    timeframe: [Jul - Dec],
    details: [
      - Raised engineers from 3x to 10x
      - Did a great job
    ],
  ),
  (
    year: 2012,
    company: [Mega Corp.],
    role: [VP of Sales],
    timeframe: [Mar - Jun],
    details: [- Closed tons of customers],
  ),
  (
    year: 2013,
    company: [Tiny Co.],
    role: [CEO],
    timeframe: [Jan - Dec],
    details: [- Delivered 4x more shareholder value],
  ),
  (
    year: 2014,
    company: [Glorbocorp Ltd],
    role: [CTO],
    timeframe: [Jan - Mar],
    details: [- Drove containerization forward],
  ),
)

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

How much to pad the cells’ content.

You can find an example for this argument at the table.inset parameter.

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 GridElem

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

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

impl Clone for GridElem

fn clone(&self) -> GridElem

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Construct for GridElem

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

Construct an element from the arguments.

impl Debug for GridElem

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

Formats the value using the given formatter.

impl Fields for GridElem

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 GridElem

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 GridElem

fn into_value(self) -> Value

Cast this type into a value.

impl NativeElement for GridElem

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 GridElem

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 GridElem

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

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

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 GridElem

fn repr(&self) -> EcoString

Return the debug representation of the value.

impl Set for GridElem

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

Parse relevant arguments into style properties for this element.