| table part | name | selection |
|---|---|---|
| header | loc.header() | composite |
| loc.title() | ||
| loc.subtitle() | ||
| boxhead | loc.column_header() | composite |
| loc.spanner_labels() | columns | |
| loc.column_labels() | columns | |
| row stub | loc.stub() | rows |
| loc.row_groups() | rows | |
| loc.grand_summary_stub() | rows | |
| table body | loc.body() | columns and rows |
| loc.grand_summary_rows() | columns and rows | |
| footer | loc.footer() | composite |
| loc.source_notes() |
Location Selection
The loc module is what connects your styling intentions to specific parts of the table. Each location specifier identifies a region of the table (such as the header, body, stub, or footer) and many of them also support targeting specific columns or rows within that region. This page provides a comprehensive overview of all available location specifiers and how to use them effectively.
Overview
Great Tables uses the loc module to specify locations for styling in tab_style(). Some location specifiers also allow selecting specific columns and rows of data.
For example, you might style a particular row name, group, column, or spanner label.
The table below shows the different location specifiers, along with the types of column or row selection they allow.
Note that composite specifiers are ones that target multiple locations. For example, loc.header() specifies both loc.title() and loc.subtitle().
Setting up data
The examples below will use this small dataset to show selecting different locations, as well as specific rows and columns within a location (where supported).
import polars as pl
import polars.selectors as cs
from great_tables import GT, loc, style, exibble
pl_exibble = pl.from_pandas(exibble)[[0, 1, 4], ["num", "char", "group"]]
pl_exibble
shape: (3, 3)
| num | char | group |
|---|---|---|
| f64 | str | str |
| 0.1111 | "apricot" | "grp_a" |
| 2.222 | "banana" | "grp_a" |
| 5550.0 | null | "grp_b" |
This small three-row, three-column dataset gives us enough structure to demonstrate row and column targeting without cluttering the output.
Simple locations
Simple locations don’t take any arguments.
For example, styling the title uses loc.title().
(
GT(pl_exibble)
.tab_header("A title", "A subtitle")
.tab_style(
style.fill("yellow"),
loc.title(),
)
)| A title | ||
| A subtitle | ||
| num | char | group |
|---|---|---|
| 0.1111 | apricot | grp_a |
| 2.222 | banana | grp_a |
| 5550.0 | None | grp_b |
Only the title receives the yellow fill; the subtitle and the rest of the table remain unstyled. Simple locations are useful when you want precise control over a single element.
Composite locations
Composite locations target multiple simple locations.
For example, loc.header() includes both loc.title() and loc.subtitle().
(
GT(pl_exibble)
.tab_header("A title", "A subtitle")
.tab_style(
style.fill("yellow"),
loc.header(),
)
)| A title | ||
| A subtitle | ||
| num | char | group |
|---|---|---|
| 0.1111 | apricot | grp_a |
| 2.222 | banana | grp_a |
| 5550.0 | None | grp_b |
Both the title and subtitle are filled with yellow because loc.header() targets the entire header region. Composite locations are a convenient shorthand when you want the same style on all sub-parts.
Body columns, rows and mask
Use columns= and rows= in loc.body() to style specific cells in the table body.
(
GT(pl_exibble).tab_style(
style.fill("yellow"),
loc.body(
columns=cs.starts_with("cha"),
rows=pl.col("char").str.contains("a"),
),
)
)| num | char | group |
|---|---|---|
| 0.1111 | apricot | grp_a |
| 2.222 | banana | grp_a |
| 5550.0 | None | grp_b |
Alternatively, use mask= in loc.body() to apply conditional styling to rows on a per-column basis.
(
GT(pl_exibble).tab_style(
style.fill("yellow"),
loc.body(mask=cs.string().str.contains("p")),
)
)| num | char | group |
|---|---|---|
| 0.1111 | apricot | grp_a |
| 2.222 | banana | grp_a |
| 5550.0 | None | grp_b |
This is discussed in detail in Styling the Table Body.
Column labels
Locations like loc.spanner_labels() and loc.column_labels() can select specific column and spanner labels.
You can use name strings, index position, or polars selectors.
GT(pl_exibble).tab_style(
style.fill("yellow"),
loc.column_labels(
cs.starts_with("cha"),
),
)| num | char | group |
|---|---|---|
| 0.1111 | apricot | grp_a |
| 2.222 | banana | grp_a |
| 5550.0 | None | grp_b |
However, note that loc.spanner_labels() currently only accepts list of string names.
Row and group names
Row and group names in loc.stub() and loc.row_groups() may be specified three ways:
- by name
- by index
- by polars expression
gt = GT(pl_exibble).tab_stub(
rowname_col="char",
groupname_col="group",
)
gt.tab_style(style.fill("yellow"), loc.stub())| num | |
|---|---|
| grp_a | |
| apricot | 0.1111 |
| banana | 2.222 |
| grp_b | |
| None | 5550.0 |
All row labels in the stub are highlighted in yellow.
gt.tab_style(style.fill("yellow"), loc.stub("banana"))| num | |
|---|---|
| grp_a | |
| apricot | 0.1111 |
| banana | 2.222 |
| grp_b | |
| None | 5550.0 |
Only the "banana" row label is styled, demonstrating name-based targeting.
gt.tab_style(style.fill("yellow"), loc.stub(["apricot", 2]))| num | |
|---|---|
| grp_a | |
| apricot | 0.1111 |
| banana | 2.222 |
| grp_b | |
| None | 5550.0 |
You can mix names and integer indices in a list to target multiple specific rows at once.
Groups by name and position
Note that for specifying row groups, the group corresponding to the group name or row number in the original data is used.
For example, the code below styles the group corresponding to the row at index 1 (i.e., the second row) in the data.
gt.tab_style(
style.fill("yellow"),
loc.row_groups(1),
)| num | |
|---|---|
| grp_a | |
| apricot | 0.1111 |
| banana | 2.222 |
| grp_b | |
| None | 5550.0 |
Since the second row (starting with “banana”) is in “grp_a”, that is the group that gets styled.
This means you can use a polars expression to select groups:
gt.tab_style(
style.fill("yellow"),
loc.row_groups(pl.col("group") == "grp_b"),
)| num | |
|---|---|
| grp_a | |
| apricot | 0.1111 |
| banana | 2.222 |
| grp_b | |
| None | 5550.0 |
You can also specify group names using a string (or list of strings).
gt.tab_style(
style.fill("yellow"),
loc.row_groups("grp_b"),
)| num | |
|---|---|
| grp_a | |
| apricot | 0.1111 |
| banana | 2.222 |
| grp_b | |
| None | 5550.0 |
The loc module provides a complete vocabulary for addressing any part of your table. By combining location specifiers with column selectors, row filters, and Polars expressions, you can apply styles to exactly the right cells. For more details on styling itself, see Styling the Table Body and Styling the Whole Table.