TypTable Full API¶

TypTable is the main builder for turning DataFrame-like data into Typst table markup. After construction, its methods configure the table by adding labels, formatting rules, styling rules, column operations, and table-level options.

Most public methods return the current table instance (Self). This makes the API fluent: each call updates the table configuration and passes the same object to the next call. Call to_typst() at the end when you want the rendered Typst string.

from typ_tables import TypTable, locators, style

typst = (
    TypTable(df, rowname_col="name")
    .tab_header("Sales by Product", subtitle="2026")
    .fmt_currency(columns="revenue", currency="USD")
    .tab_style(
        locator=locators.LocBody(columns="revenue"),
        cell=style.CellStyle(align="right"),
    )
    .to_typst()
)

Table Creation and Rendering¶

typ_tables.TypTable ¶

Build a Typst table from a DataFrame-like object.

TypTable stores the source data plus table configuration such as formatting rules, labels, styling, row stubs, row groups, and Typst table options. Input data is normalized with Narwhals, so any eager DataFrame-like object supported by Narwhals can be used.

init ¶

__init__(
    df: IntoDataFrame,
    rowname_col: str | None = None,
    groupname_col: str | None = None,
) -> None

Parameters:

Name	Type	Description	Default
`df`	`IntoDataFrame`	Input DataFrame supported by Narwhals.	required
`rowname_col`	`str \| None`	Optional column used as row labels (stub column).	`None`
`groupname_col`	`str \| None`	Optional column used to group rows.	`None`

Raises:

Type	Description
`ValueError`	If `df` has zero columns.
`ValueError`	If `groupname_col` is set without `rowname_col`.

to_typst ¶

to_typst() -> str

Render the configured table as Typst markup.

Returns:

Type	Description
`str`	Complete Typst string representing the table.

Modifying the Table¶

typ_tables.TypTable.tab_header ¶

tab_header(
    title: str | Typst, subtitle: str | Typst | None = None
) -> t.Self

Set table title and optional subtitle.

The header is rendered above the column-label row and spans the full table width. This method changes only that title/subtitle region; it does not change column labels, row labels, or body cells.

Parameters:

Name	Type	Description	Default
`title`	`str \| Typst`	Title text or raw Typst.	required
`subtitle`	`str \| Typst \| None`	Optional subtitle text or raw Typst.	`None`

Returns:

Type	Description
`Self`	The current table instance for chaining.

typ_tables.TypTable.tab_figure ¶

tab_figure(caption: str | Typst | None = None) -> t.Self

Configure an optional figure caption wrapper around the table.

When caption is provided, the rendered Typst table is wrapped in a Typst figure and the caption is attached to that figure. Passing None disables the figure wrapper and leaves the table itself unchanged.

Parameters:

Name	Type	Description	Default
`caption`	`str \| Typst \| None`	Caption text or raw Typst. `None` disables wrapping.	`None`

Returns:

Type	Description
`Self`	The current table instance for chaining.

typ_tables.TypTable.tab_stubhead ¶

tab_stubhead(label: str | Typst) -> t.Self

Set the label shown in the stub header cell.

The stub head is the top-left header cell above the row-label stub column. This method changes only that stub-head label; it does not rename row labels or data columns. The cell is only visible when the table has a stub column.

Parameters:

Name	Type	Description	Default
`label`	`str \| Typst`	Stub header label text or raw Typst.	required

Returns:

Type	Description
`Self`	The current table instance for chaining.

typ_tables.TypTable.tab_spanner ¶

tab_spanner(
    label: str | Typst,
    columns: ColumnSelector | None = None,
    spanners: str | list[str] | None = None,
    level: int | None = None,
    id_: str | None = None,
    gather: bool = True,
) -> t.Self

Add a column spanner above selected columns or existing spanners.

A spanner is a header cell that spans multiple columns. Select columns directly with columns, or select existing spanners by ID with spanners to create a higher-level grouped header. When level is not provided, the spanner is placed on the lowest level that does not overlap existing spanners.

Parameters:

Name	Type	Description	Default
`label`	`str \| Typst`	Spanner label text or raw Typst.	required
`columns`	`ColumnSelector \| None`	Optional selector for columns to include in the spanner.	`None`
`spanners`	`str \| list[str] \| None`	Optional existing spanner ID or IDs whose columns should be included in the new spanner.	`None`
`level`	`int \| None`	Optional zero-based spanner level. If provided, overlapping spanners on that level have the new spanner's columns removed.	`None`
`id_`	`str \| None`	Optional unique identifier for the spanner. Defaults to `str(label)`.	`None`
`gather`	`bool`	Whether to move directly selected columns next to the first selected column when adding a bottom-level spanner.	`True`

Raises:

Type	Description
`NotImplementedError`	If neither `columns` nor `spanners` is provided.
`ValueError`	If `level` is negative, `id_` duplicates an existing spanner ID, or a referenced spanner ID does not exist.
`ColumnNotFoundError`	If `columns` references unknown columns.

Returns:

Type	Description
`Self`	The current table instance for chaining.

typ_tables.TypTable.tab_footer ¶

tab_footer(note: str | Typst) -> t.Self

Add a note to the table footer.

Footer notes are rendered below the table body in a single footer cell that spans the full table width. Repeated calls append additional notes to the same footer, separated by Typst line breaks.

Parameters:

Name	Type	Description	Default
`note`	`str \| Typst`	Footer note text or raw Typst.	required

Returns:

Type	Description
`Self`	The current table instance for chaining.

Styling the Table¶

typ_tables.TypTable.tab_style ¶

tab_style(
    locator: Loc,
    text: TextStyle | None = None,
    cell: CellStyle | None = None,
) -> t.Self

Add style rules for a specific table region.

Locators define which table region receives the supplied text style, cell style, or both. Use LocHeader for the title/subtitle region, LocColumnLabels for column names, LocStub for row labels, LocStubhead for the top-left stub label, LocBody for data cells, and LocRowGroup for row-group labels.

Parameters:

Name	Type	Description	Default
`locator`	`Loc`	Target region selector (for example `locators.LocHeader`).	required
`text`	`TextStyle \| None`	Optional text-level style settings.	`None`
`cell`	`CellStyle \| None`	Optional cell-level style settings.	`None`

Returns:

Type	Description
`Self`	The current table instance for chaining.

Formatting Cell Contents¶

typ_tables.TypTable.sub_missing ¶

sub_missing(
    columns: ColumnSelector | None = None,
    rows: RowSelector | None = None,
    *,
    missing_text: str = "",
) -> t.Self

Replace null-like values in selected cells.

Parameters:

Name	Type	Description	Default
`columns`	`ColumnSelector \| None`	Optional column selector limiting where substitution applies.	`None`
`rows`	`RowSelector \| None`	Optional row selector limiting where substitution applies.	`None`
`missing_text`	`str`	Replacement text used for missing values.	`''`

Returns:

Type	Description
`Self`	The current table instance for chaining.

typ_tables.TypTable.fmt ¶

fmt(
    columns: ColumnSelector | None = None,
    rows: RowSelector | None = None,
    *,
    f_string: str,
) -> t.Self

Format selected values with a Narwhals-style f-string.

Parameters:

Name	Type	Description	Default
`columns`	`ColumnSelector \| None`	Optional column selector limiting where formatting applies.	`None`
`rows`	`RowSelector \| None`	Optional row selector limiting where formatting applies.	`None`
`f_string`	`str`	Format string used to render each selected value.	required

Returns:

Type	Description
`Self`	The current table instance for chaining.

Note

Currently only accepts 1 placeholder.

typ_tables.TypTable.fmt_number ¶

fmt_number(
    columns: ColumnSelector | None = None,
    rows: RowSelector | None = None,
    *,
    decimals: int = 2,
    n_sigfig: int | None = None,
    drop_trailing_zeros: bool = False,
    drop_trailing_dec_mark: bool = True,
    use_seps: bool = True,
    accounting: bool = False,
    scale_by: float = 1,
    compact: bool = False,
    pattern: str = "{x}",
    dec_mark: str = ".",
    sep_mark: str = ",",
    force_sign: bool = False,
) -> t.Self

Format selected numeric values with configurable numeric rules.

Parameters:

Name	Type	Description	Default
`columns`	`ColumnSelector \| None`	Optional column selector limiting where formatting applies.	`None`
`rows`	`RowSelector \| None`	Optional row selector limiting where formatting applies.	`None`
`decimals`	`int`	Number of decimal places.	`2`
`n_sigfig`	`int \| None`	Optional number of significant figures.	`None`
`drop_trailing_zeros`	`bool`	Whether to remove trailing zero digits.	`False`
`drop_trailing_dec_mark`	`bool`	Whether to remove dangling decimal marks.	`True`
`use_seps`	`bool`	Whether to include thousands separators.	`True`
`accounting`	`bool`	Whether to use accounting-style negatives.	`False`
`scale_by`	`float`	Multiplicative scaling factor before formatting.	`1`
`compact`	`bool`	Whether to compact large numbers (for example, `1K`).	`False`
`pattern`	`str`	Output pattern containing `{x}` placeholder.	`'{x}'`
`dec_mark`	`str`	Decimal mark character.	`'.'`
`sep_mark`	`str`	Thousands separator character.	`','`
`force_sign`	`bool`	Whether to always show explicit sign symbols.	`False`

Returns:

Type	Description
`Self`	The current table instance for chaining.

typ_tables.TypTable.fmt_integer ¶

fmt_integer(
    columns: ColumnSelector | None = None,
    rows: RowSelector | None = None,
    *,
    use_seps: bool = True,
    accounting: bool = False,
    scale_by: float = 1,
    compact: bool = False,
    pattern: str = "{x}",
    sep_mark: str = ",",
    force_sign: bool = False,
) -> t.Self

Format selected integer values with configurable integer rules.

Parameters:

Name	Type	Description	Default
`columns`	`ColumnSelector \| None`	Optional column selector limiting where formatting applies.	`None`
`rows`	`RowSelector \| None`	Optional row selector limiting where formatting applies.	`None`
`use_seps`	`bool`	Whether to include thousands separators.	`True`
`accounting`	`bool`	Whether to use accounting-style negatives.	`False`
`scale_by`	`float`	Multiplicative scaling factor before formatting.	`1`
`compact`	`bool`	Whether to compact large numbers (for example, `1K`).	`False`
`pattern`	`str`	Output pattern containing `{x}` placeholder.	`'{x}'`
`sep_mark`	`str`	Thousands separator character.	`','`
`force_sign`	`bool`	Whether to always show explicit sign symbols.	`False`

Returns:

Type	Description
`Self`	The current table instance for chaining.

typ_tables.TypTable.fmt_percentage ¶

fmt_percentage(
    columns: ColumnSelector | None = None,
    rows: RowSelector | None = None,
    *,
    decimals: int = 2,
    drop_trailing_zeros: bool = False,
    drop_trailing_dec_mark: bool = True,
    scale_values: bool = True,
    use_seps: bool = True,
    accounting: bool = False,
    pattern: str = "{x}",
    dec_mark: str = ".",
    sep_mark: str = ",",
    force_sign: bool = False,
    placement: Placement = "right",
    incl_space: bool = False,
) -> t.Self

Format selected numeric values as percentages.

Parameters:

Name	Type	Description	Default
`columns`	`ColumnSelector \| None`	Optional column selector limiting where formatting applies.	`None`
`rows`	`RowSelector \| None`	Optional row selector limiting where formatting applies.	`None`
`decimals`	`int`	Number of decimal places.	`2`
`drop_trailing_zeros`	`bool`	Whether to remove trailing zero digits.	`False`
`drop_trailing_dec_mark`	`bool`	Whether to remove dangling decimal marks.	`True`
`scale_values`	`bool`	Should the values be scaled through multiplication by 100?	`True`
`use_seps`	`bool`	Whether to include thousands separators.	`True`
`accounting`	`bool`	Whether to use accounting-style negatives.	`False`
`pattern`	`str`	Output pattern containing `{x}` placeholder.	`'{x}'`
`sep_mark`	`str`	Thousands separator character.	`','`
`dec_mark`	`str`	Decimal mark character.	`'.'`
`force_sign`	`bool`	Whether to always show explicit sign symbols.	`False`
`placement`	`Placement`	Where to place the percent sign. Can be `left` or `right`.	`'right'`
`incl_space`	`bool`	An option for whether to include a space between the value and the percent sign.	`False`

Returns:

Type	Description
`Self`	The current table instance for chaining.

typ_tables.TypTable.fmt_scientific ¶

fmt_scientific(
    columns: ColumnSelector | None = None,
    rows: RowSelector | None = None,
    *,
    decimals: int = 2,
    n_sigfig: int | None = None,
    drop_trailing_zeros: bool = False,
    drop_trailing_dec_mark: bool = True,
    scale_by: float = 1,
    pattern: str = "{x}",
    sep_mark: str = ",",
    dec_mark: str = ".",
    force_sign_m: bool = False,
    force_sign_n: bool = False,
) -> t.Self

Format selected numeric values in scientific notation.

Parameters:

Name	Type	Description	Default
`columns`	`ColumnSelector \| None`	Optional column selector limiting where formatting applies.	`None`
`rows`	`RowSelector \| None`	Optional row selector limiting where formatting applies.	`None`
`decimals`	`int`	Number of decimal places.	`2`
`n_sigfig`	`int \| None`	Optional number of significant figures.	`None`
`drop_trailing_zeros`	`bool`	Whether to remove trailing zero digits.	`False`
`drop_trailing_dec_mark`	`bool`	Whether to remove dangling decimal marks.	`True`
`scale_by`	`float`	Multiplicative scaling factor before formatting.	`1`
`pattern`	`str`	Output pattern containing `{x}` placeholder.	`'{x}'`
`sep_mark`	`str`	Thousands separator character.	`','`
`dec_mark`	`str`	Decimal mark character.	`'.'`
`force_sign_m`	`bool`	Should the plus sign be shown for positive values of the mantissa (first component)?	`False`
`force_sign_n`	`bool`	Should the plus sign be shown for positive values of the exponent (second component)?	`False`

Returns:

Type	Description
`Self`	The current table instance for chaining.

typ_tables.TypTable.fmt_engineering ¶

fmt_engineering(
    columns: ColumnSelector | None = None,
    rows: RowSelector | None = None,
    *,
    decimals: int = 2,
    n_sigfig: int | None = None,
    drop_trailing_zeros: bool = False,
    drop_trailing_dec_mark: bool = True,
    scale_by: float = 1,
    pattern: str = "{x}",
    sep_mark: str = ",",
    dec_mark: str = ".",
    force_sign_m: bool = False,
    force_sign_n: bool = False,
) -> t.Self

Format selected numeric values with engineering notation.

Engineering notation is like scientific notation, but the exponent is always a multiple of 3. This makes it convenient for expressing values in SI units, such as 1.23E3 for thousands or 1.23E6 for millions.

Parameters:

Name	Type	Description	Default
`columns`	`ColumnSelector \| None`	Optional column selector limiting where formatting applies.	`None`
`rows`	`RowSelector \| None`	Optional row selector limiting where formatting applies.	`None`
`decimals`	`int`	Number of decimal places.	`2`
`n_sigfig`	`int \| None`	Optional number of significant figures.	`None`
`drop_trailing_zeros`	`bool`	Whether to remove trailing zero digits.	`False`
`drop_trailing_dec_mark`	`bool`	Whether to remove dangling decimal marks.	`True`
`scale_by`	`float`	Multiplicative scaling factor before formatting.	`1`
`pattern`	`str`	Output pattern containing `{x}` placeholder.	`'{x}'`
`sep_mark`	`str`	Thousands separator character.	`','`
`dec_mark`	`str`	Decimal mark character.	`'.'`
`force_sign_m`	`bool`	Should the plus sign be shown for positive values of the mantissa (first component)?	`False`
`force_sign_n`	`bool`	Should the plus sign be shown for positive values of the exponent (second component)?	`False`

Returns:

Type	Description
`Self`	The current table instance for chaining.

typ_tables.TypTable.fmt_currency ¶

fmt_currency(
    columns: ColumnSelector | None = None,
    rows: RowSelector | None = None,
    *,
    currency: str,
    use_subunits: bool = True,
    decimals: int = 2,
    drop_trailing_dec_mark: bool = True,
    use_seps: bool = True,
    accounting: bool = False,
    scale_by: float = 1,
    compact: bool = False,
    pattern: str = "{x}",
    sep_mark: str = ",",
    dec_mark: str = ".",
    force_sign: bool = False,
    placement: Placement = "left",
    incl_space: bool = False,
) -> t.Self

Format selected numeric values as currency.

Currency symbols are resolved from the supplied three-letter currency code. Numeric formatting options follow the same conventions as fmt_number.

Parameters:

Name	Type	Description	Default
`columns`	`ColumnSelector \| None`	Optional column selector limiting where formatting applies.	`None`
`rows`	`RowSelector \| None`	Optional row selector limiting where formatting applies.	`None`
`currency`	`str`	The currency to use for the numeric value. This input can be supplied as a 3-letter currency code.	required
`use_subunits`	`bool`	An option for whether the subunits portion of a currency value should be displayed.	`True`
`decimals`	`int`	Number of decimal places.	`2`
`drop_trailing_dec_mark`	`bool`	Whether to remove dangling decimal marks.	`True`
`use_seps`	`bool`	Whether to include thousands separators.	`True`
`accounting`	`bool`	Whether to use accounting style, which wraps negative numbers in parentheses instead of using a minus sign.	`False`
`scale_by`	`float`	Multiplicative scaling factor before formatting.	`1`
`compact`	`bool`	Whether to compact large numbers (for example, `1K`).	`False`
`pattern`	`str`	Output pattern containing `{x}` placeholder.	`'{x}'`
`sep_mark`	`str`	Thousands separator character.	`','`
`dec_mark`	`str`	Decimal mark character.	`'.'`
`force_sign`	`bool`	Whether to always show explicit sign symbols.	`False`
`placement`	`Placement`	Where to place the currency sign. Can be `left` or `right`.	`'left'`
`incl_space`	`bool`	An option for whether to include a space between the value and the currency sign.	`False`

Returns:

Type	Description
`Self`	The current table instance for chaining.

typ_tables.TypTable.fmt_date ¶

fmt_date(
    columns: ColumnSelector | None = None,
    rows: RowSelector | None = None,
    *,
    date_style: DateStyle = "iso",
    pattern: str = "{x}",
) -> t.Self

Format selected date values with configurable date rules.

Parameters:

Name	Type	Description	Default
`columns`	`ColumnSelector \| None`	Optional column selector limiting where formatting applies.	`None`
`rows`	`RowSelector \| None`	Optional row selector limiting where formatting applies.	`None`
`date_style`	`DateStyle`	The date style to use for formatting.	`'iso'`
`pattern`	`str`	Output pattern containing `{x}` placeholder.	`'{x}'`

Returns:

Type	Description
`Self`	The current table instance for chaining.

typ_tables.TypTable.fmt_time ¶

fmt_time(
    columns: ColumnSelector | None = None,
    rows: RowSelector | None = None,
    *,
    time_style: TimeStyle = "iso",
    pattern: str = "{x}",
) -> t.Self

Format selected time values with configurable time rules.

Parameters:

Name	Type	Description	Default
`columns`	`ColumnSelector \| None`	Optional column selector limiting where formatting applies.	`None`
`rows`	`RowSelector \| None`	Optional row selector limiting where formatting applies.	`None`
`time_style`	`TimeStyle`	The time style to use for formatting.	`'iso'`
`pattern`	`str`	Output pattern containing `{x}` placeholder.	`'{x}'`

Returns:

Type	Description
`Self`	The current table instance for chaining.

typ_tables.TypTable.fmt_datetime ¶

fmt_datetime(
    columns: ColumnSelector | None = None,
    rows: RowSelector | None = None,
    *,
    date_style: DateStyle = "iso",
    time_style: TimeStyle = "iso",
    format_str: str | None = None,
    sep: str = " ",
    pattern: str = "{x}",
) -> t.Self

Format selected datetime values with configurable date and time rules.

Parameters:

Name	Type	Description	Default
`columns`	`ColumnSelector \| None`	Optional column selector limiting where formatting applies.	`None`
`rows`	`RowSelector \| None`	Optional row selector limiting where formatting applies.	`None`
`date_style`	`DateStyle`	The date style to use for formatting.	`'iso'`
`time_style`	`TimeStyle`	The time style to use for formatting.	`'iso'`
`format_str`	`str \| None`	Optional strftime format string. If provided, date_style and time_style are ignored.	`None`
`sep`	`str`	Separator between date and time components.	`' '`
`pattern`	`str`	Output pattern containing `{x}` placeholder.	`'{x}'`

Returns:

Type	Description
`Self`	The current table instance for chaining.

typ_tables.TypTable.fmt_tf ¶

fmt_tf(
    columns: ColumnSelector | None = None,
    rows: RowSelector | None = None,
    *,
    tf_style: TfStyle = "true-false",
    pattern: str = "{x}",
    true_val: str | None = None,
    false_val: str | None = None,
    na_val: str | None = None,
) -> t.Self

Format selected boolean values with configurable True/False rules.

There can be times where boolean values are useful in a display table. You might want to express a 'yes' or 'no', a 'true' or 'false', or, perhaps use pairings of complementary symbols that make sense in a table. The fmt_tf() method has a set of tf_style= presets that can be used to quickly map True/False values to strings, or, symbols like up/down or left/right arrows and open/closed shapes.

While the presets are nice, you can provide your own mappings through the true_val= and false_val= arguments. For extra customization, you can also handle missing values with the na_val= option.

Parameters:

Name	Type	Description	Default
`columns`	`ColumnSelector \| None`	Optional column selector limiting where formatting applies.	`None`
`rows`	`RowSelector \| None`	Optional row selector limiting where formatting applies.	`None`
`tf_style`	`TfStyle`	The `True`/`False` mapping style to use. By default this is the short name `"true-false"` which corresponds to the words `"true"` and `"false"`. Two other `tf_style=` values produce words: `"yes-no"` and `"up-down"`. The remaining options involve pairs of symbols (e.g., `"check-mark"` displays a check mark for `True` and an ✗ symbol for `False`).	`'true-false'`
`pattern`	`str`	A formatting pattern that allows for decoration of the formatted value. The formatted value is represented by the `{x}` (which can be used multiple times, if needed) and all other characters will be interpreted as string literals.	`'{x}'`
`true_val`	`str \| None`	While the choice of a `tf_style=` will typically supply the `true_val=` and `false_val=` text, we could override this and supply text for any `True` values. This doesn't need to be used in conjunction with `false_val=`.	`None`
`false_val`	`str \| None`	While the choice of a `tf_style=` will typically supply the `true_val=` and `false_val=` text, we could override this and supply text for any `False` values. This doesn't need to be used in conjunction with `true_val=`.	`None`
`na_val`	`str \| None`	None of the `tf_style` presets will replace any missing values encountered in the targeted cells. While we always have the option to use `sub_missing()` for NA replacement, we have the opportunity handle missing values here with the `na_val=` option.	`None`

Returns:

Type	Description
`Self`	The current table instance for chaining.

Note

Formatting with the tf_style= argument:

We need to supply a preset tf_style= value. The following table provides a listing of all tf_style= values and their output True and False values.

	TF Style	Output
1	`"true-false"`	`"true"` / `"false"`
2	`"yes-no"`	`"yes"` / `"no"`
3	`"up-down"`	`"up"` / `"down"`
4	`"check-mark"`	`#sym.checkmark` / `#sym.crossmark`
5	`"circles"`	`#sym.circle.filled` / `#sym.circle`
6	`"squares"`	`#sym.square.filled` / `#sym.square`
7	`"diamonds"`	`#sym.diamond.filled` / `#sym.diamond`
8	`"arrows"`	`#sym.arrow.t` / `#sym.arrow.b`
9	`"triangles"`	`#sym.triangle.filled.t` / `#sym.triangle.filled.b`
10	`"triangles-lr"`	`#sym.triangle.filled.r` / `#sym.triangle.filled.l`

typ_tables.TypTable.fmt_bytes ¶

fmt_bytes(
    columns: ColumnSelector | None = None,
    rows: RowSelector | None = None,
    *,
    standard: BytesStyle = "decimal",
    decimals: int = 1,
    n_sigfig: int | None = None,
    drop_trailing_zeros: bool = True,
    drop_trailing_dec_mark: bool = True,
    use_seps: bool = True,
    pattern: str = "{x}",
    sep_mark: str = ",",
    dec_mark: str = ".",
    force_sign: bool = False,
    incl_space: bool = True,
) -> t.Self

Format selected numeric values as bytes with human-readable units.

With numeric values in a table, we can transform those to values of bytes with human readable units. The fmt_bytes() method allows for the formatting of byte sizes to either of two common representations: (1) with decimal units (powers of 1000, examples being "kB" and "MB"), and (2) with binary units (powers of 1024, examples being "KiB" and `"MiB"). It is assumed the input numeric values represent the number of bytes and automatic truncation of values will occur. The numeric values will be scaled to be in the range of 1 to <1000 and then decorated with the correct unit symbol according to the standard chosen.

Parameters:

Name	Type	Description	Default
`columns`	`ColumnSelector \| None`	Optional column selector limiting where formatting applies.	`None`
`rows`	`RowSelector \| None`	Optional row selector limiting where formatting applies.	`None`
`standard`	`BytesStyle`	The form of expressing large byte sizes is divided between: (1) decimal units (powers of 1000; e.g., `"kB"` and `"MB"`), and (2) binary units (powers of 1024; e.g., `"KiB"` and `"MiB"`). The default is to use decimal units with the `"decimal"` option. The alternative is to use binary units with the `"binary"` option.	`'decimal'`
`decimals`	`int`	This corresponds to the exact number of decimal places to use. A value such as `2.34` can, for example, be formatted with `0` decimal places and it would result in `"2"`. With `4` decimal places, the formatted value becomes `"2.3400"`. The trailing zeros can be removed with `drop_trailing_zeros=True`.	`1`
`n_sigfig`	`int \| None`	Optional number of significant figures.	`None`
`drop_trailing_zeros`	`bool`	A boolean value that allows for removal of trailing zeros (those redundant zeros after the decimal mark).	`True`
`drop_trailing_dec_mark`	`bool`	A boolean value that determines whether decimal marks should always appear even if there are no decimal digits to display after formatting (e.g., `23` becomes `23.` if `False`). By default trailing decimal marks are not shown.	`True`
`use_seps`	`bool`	The `use_seps` option allows for the use of digit group separators. The type of digit group separator is set by `sep_mark`.	`True`
`pattern`	`str`	A formatting pattern that allows for decoration of the formatted value. The formatted value is represented by the `{x}` (which can be used multiple times, if needed) and all other characters will be interpreted as string literals.	`'{x}'`
`sep_mark`	`str`	The string to use as a separator between groups of digits. For example, using `sep_mark=","` with a value of `1000` would result in a formatted value of `"1,000"`.	`','`
`dec_mark`	`str`	The string to be used as the decimal mark. For example, using `dec_mark=","` with the value `0.152` would result in a formatted value of `"0,152"`.	`'.'`
`force_sign`	`bool`	Should the positive sign be shown for positive values (effectively showing a sign for all values except zero)? If so, use `True` for this option. The default is `False`, where only negative numbers will display a minus sign.	`False`
`incl_space`	`bool`	An option for whether to include a space between the value and the unit symbol. The default is to include a space character.	`True`

Returns:

Type	Description
`Self`	The current table instance for chaining.

Modifying Columns¶

typ_tables.TypTable.cols_align ¶

cols_align(
    align: Alignment = "left",
    columns: ColumnSelector | None = None,
) -> t.Self

Set text alignment for selected columns.

Alignment applies to both column-label cells and body cells for the selected columns. It does not affect unselected columns, row-group labels, or the table title/subtitle.

Parameters:

Name	Type	Description	Default
`align`	`Alignment`	Target alignment value.	`'left'`
`columns`	`ColumnSelector \| None`	Optional column selector; defaults to all columns.	`None`

Returns:

Type	Description
`Self`	The current table instance for chaining.

typ_tables.TypTable.cols_hide ¶

cols_hide(columns: ColumnSelector | None = None) -> t.Self

Hide selected columns from the rendered output.

Hidden columns are omitted completely, including their column labels and body cells. The source data is not modified, so later calls can still refer to hidden columns by their original names.

Parameters:

Name	Type	Description	Default
`columns`	`ColumnSelector \| None`	Optional column selector; defaults to all columns.	`None`

Returns:

Type	Description
`Self`	The current table instance for chaining.

typ_tables.TypTable.cols_label ¶

cols_label(
    cases: dict[str, str | Typst] | None = None,
    **kwargs: str | Typst,
) -> t.Self

Set explicit labels for one or more columns.

Labels replace the displayed column names without changing the source data or the selectors used by later calls. This method changes only column-label text; it does not format body values.

Parameters:

Name	Type	Description	Default
`cases`	`dict[str, str \| Typst] \| None`	Optional mapping of column names to new labels.	`None`
`**kwargs`	`str \| Typst`	Additional column-to-label mappings.	`{}`

Returns:

Type	Description
`Self`	The current table instance for chaining.

typ_tables.TypTable.cols_label_with ¶

cols_label_with(
    fn: Callable[[str], str | Typst],
    columns: ColumnSelector | None = None,
) -> t.Self

Relabel selected columns using a mapping function.

The function receives each selected source column name and returns the label to display. This method changes only the visible column labels; source column names and body values are unchanged.

Parameters:

Name	Type	Description	Default
`fn`	`Callable[[str], str \| Typst]`	Function receiving current column name and returning new label.	required
`columns`	`ColumnSelector \| None`	Optional column selector; defaults to all columns.	`None`

Returns:

Type	Description
`Self`	The current table instance for chaining.

Table Options¶

typ_tables.TypTable.set_table_inset ¶

set_table_inset(
    inset: str | Sides[Relative] | dict[str, Relative],
) -> t.Self

Set default padding for every table cell.

This controls table-level cell inset. Region-specific CellStyle rules can still override inset for targeted cells.

Parameters:

Name	Type	Description	Default
`inset`	`str \| Sides[Relative] \| dict[str, Relative]`	Typst inset value, per-side `Sides`, or dictionary accepted by `Sides`.	required

Returns:

Type	Description
`Self`	The current table instance for chaining.

typ_tables.TypTable.set_table_stroke ¶

set_table_stroke(stroke: str) -> t.Self

Set the table-level stroke.

This controls the default stroke passed to Typst's table function. Region-specific cell styles can still override strokes for targeted cells.

Parameters:

Name	Type	Description	Default
`stroke`	`str`	Raw Typst stroke expression.	required

Returns:

Type	Description
`Self`	The current table instance for chaining.

typ_tables.TypTable.set_gutter ¶

set_gutter(
    gutter: Gutter | None = None,
    row_gutter: Gutter | None = None,
    column_gutter: Gutter | None = None,
) -> t.Self

Set spacing between rows and columns.

gutter sets Typst's general table gutter. row_gutter and column_gutter override spacing in one direction.

Parameters:

Name	Type	Description	Default
`gutter`	`Gutter \| None`	Default row and column gutter.	`None`
`row_gutter`	`Gutter \| None`	Row-only gutter override.	`None`
`column_gutter`	`Gutter \| None`	Column-only gutter override.	`None`

Returns:

Type	Description
`Self`	The current table instance for chaining.

typ_tables.TypTable.clear_defaults ¶

clear_defaults() -> t.Self

Clear all typ-tables default styling.

This removes typ-tables' opinionated default styles and resets the table-level stroke to Typst's default-style baseline.

Returns:

Type	Description
`Self`	The current table instance for chaining.

Pipeline¶

typ_tables.TypTable.pipe ¶

pipe(
    func: Callable[Concatenate[Self, P], Self],
    *args: args,
    **kwargs: kwargs,
) -> t.Self

Method to apply a function on a TypTable object in a method call chain.

Parameters:

Name	Type	Description	Default
`func`	`Callable[Concatenate[Self, P], Self]`	A function that takes a TypTable as the first argument, and then any number of positional or keyword arguments. It then returns a TypTable object.	required
`*args`	`args`	The optional positional arguments that func needs.	`()`
`**kwargs`	`kwargs`	The optional keyword arguments that func needs.	`{}`

Example

def colour_max(tbl: TypTable, columns: list[str]) -> TypTable:
    for column in columns:
        tbl = tbl.tab_style(
            cell=style.CellStyle(fill="red"),
            locator=locators.LocBody(
                columns=column, rows=(nw.col(column) == nw.col(column).max())
            ),
        )
    return tbl


TypTable(data).pipe(colour_max, ["column_a", "column_b"])

Returns:

Type	Description
`Self`	The current table instance for chaining.

TypTable Full API¶

Table Creation and Rendering¶

typ_tables.TypTable ¶

__init__ ¶

to_typst ¶

Modifying the Table¶

typ_tables.TypTable.tab_header ¶

typ_tables.TypTable.tab_figure ¶

typ_tables.TypTable.tab_stubhead ¶

typ_tables.TypTable.tab_spanner ¶

typ_tables.TypTable.tab_footer ¶

Styling the Table¶

typ_tables.TypTable.tab_style ¶

Formatting Cell Contents¶

typ_tables.TypTable.sub_missing ¶

typ_tables.TypTable.fmt ¶

typ_tables.TypTable.fmt_number ¶

typ_tables.TypTable.fmt_integer ¶

typ_tables.TypTable.fmt_percentage ¶

typ_tables.TypTable.fmt_scientific ¶

typ_tables.TypTable.fmt_engineering ¶

typ_tables.TypTable.fmt_currency ¶

typ_tables.TypTable.fmt_date ¶

typ_tables.TypTable.fmt_time ¶

typ_tables.TypTable.fmt_datetime ¶

typ_tables.TypTable.fmt_tf ¶

typ_tables.TypTable.fmt_bytes ¶

Modifying Columns¶

typ_tables.TypTable.cols_align ¶

typ_tables.TypTable.cols_hide ¶

typ_tables.TypTable.cols_label ¶

typ_tables.TypTable.cols_label_with ¶

Table Options¶

typ_tables.TypTable.set_table_inset ¶

typ_tables.TypTable.set_table_stroke ¶

typ_tables.TypTable.set_gutter ¶

typ_tables.TypTable.clear_defaults ¶

Pipeline¶

typ_tables.TypTable.pipe ¶

init ¶