tbl_preview()

Generate a self-contained HTML table preview from almost any tabular data source.

Usage

tbl_preview(
    data,
    columns=None,
    n_head=5,
    n_tail=5,
    limit=50,
    show_all=False,
    show_row_numbers=True,
    show_dtypes=True,
    show_dimensions=True,
    max_col_width=250,
    min_tbl_width=500,
    caption=None,
    highlight_missing=True,
    row_index_offset=0,
    id=None
)

The tbl_preview() function gives you a quick, polished look at a dataset without pulling in heavy rendering dependencies. Pass it a Polars DataFrame, a Pandas DataFrame, a PyArrow Table, a file path to a CSV / TSV / JSONL / Parquet / Feather file, a column-oriented dictionary, or a list of row dictionaries—and get back a styled HTML table that renders identically in notebooks, Quarto documents, and static HTML pages.

The preview shows a configurable number of rows from the top and bottom of the table, separated by a blue divider line when the full dataset exceeds the requested row count. Each column header displays the column name and, beneath it, a compact dtype label (e.g., i64, str, f64). A header banner shows a colored badge identifying the data source type (Polars, Pandas, CSV, Parquet, etc.) alongside row and column counts. Missing values (None, NaN, NA) are highlighted in red so they stand out immediately.

The output is a TblPreview object with _repr_html_() support, so it displays automatically in Jupyter notebooks and Quarto code cells. All CSS is scoped to a unique id, and the table includes full dark-mode support. No JavaScript is required.

Parameters

data: Any: The table to preview. This can be a Polars DataFrame, a Pandas DataFrame, a PyArrow Table, a file path (as a string or pathlib.Path object), a column-oriented dictionary, or a list of row dictionaries. When providing a file path, the extension determines the loader: .csv, .tsv, .jsonl (or .ndjson), .parquet, .feather, and .arrow (Arrow IPC) are all supported. Read the Supported Input Data Types section for details on each accepted format.
columns: list[str] | None = None: The columns to display in the preview, by default None (all columns are shown). This can be a list of column name strings. If any name does not match a column in the table, a KeyError is raised. This is useful for focusing on a subset of a wide dataset.
n_head: int = 5: The number of rows to show from the start of the table. Set to 5 by default. When the table has fewer rows than n_head + n_tail, the full table is displayed without a divider.
n_tail: int = 5: The number of rows to show from the end of the table. Set to 5 by default.
limit: int = 50: The limit value for the sum of n_head= and n_tail= (the total number of rows shown). If the sum of n_head= and n_tail= exceeds the limit, a ValueError is raised. The default value is 50. Increase this when you need to display more rows.
show_all: bool = False: Should the entire table be displayed? If True, all rows are shown regardless of the n_head= and n_tail= settings. By default, this is False.
show_row_numbers: bool = True: Should row numbers be shown? The numbers appear in a narrow gutter column on the left side of the table, separated from the data columns by a subtle blue vertical line. By default, this is set to True.
show_dtypes: bool = True: Should data type labels be displayed beneath each column name? The labels use short abbreviations (e.g., i64 for 64-bit integer, str for string, f64 for 64-bit float). By default, this is set to True.
show_dimensions: bool = True: Should the header banner be shown? The banner displays a colored badge identifying the data source type alongside row and column counts in labeled pill badges. By default, this is set to True.
max_col_width: int = 250: The maximum width of any single column in pixels. Column widths are computed automatically to fit their content up to this ceiling, beyond which cell text is truncated with an ellipsis. The default value is 250 pixels.
min_tbl_width: int = 500: The minimum total width of the table in pixels. If the sum of the computed column widths is less than this value, columns are proportionally widened to fill the available space. The default value is 500 pixels.
caption: str | None = None: An optional caption string displayed below the header banner and above the column headers. Useful for labeling a preview with a dataset name or description. By default, no caption is shown.
highlight_missing: bool = True: Should missing values (None, NaN, NA) be highlighted? When True (the default), missing cells are displayed in red text on a light red background so they stand out at a glance.
row_index_offset: int = 0: The starting number for row indices. Defaults to 0, matching the zero-based indexing convention of Python, Polars, and Pandas. Set to 1 for one-based numbering (e.g., for presentation to audiences unfamiliar with zero-based indexing).
id: str | None = None: An HTML id attribute for the outer <div> container. If None (the default), a unique ID is auto-generated using secrets.token_hex(4). Providing your own ID is useful when you need to target the table with custom CSS or JavaScript.

Returns

TblPreview: A rendered table preview object. The object has _repr_html_() for automatic notebook display.

Supported Input Data Types

The data parameter accepts any of the following:

Polars DataFrame — displays a blue Polars badge
Pandas DataFrame — displays a dark purple Pandas badge
PyArrow Table — displays an indigo Arrow badge
CSV file (.csv) — loaded automatically; displays a cream CSV badge
TSV file (.tsv) — loaded automatically; displays a green TSV badge
JSONL file (.jsonl or .ndjson) — loaded line-by-line; displays a blue JSONL badge
Parquet file (.parquet) — requires polars, pandas, or pyarrow; displays a purple Parquet badge
Feather / Arrow IPC file (.feather or .arrow) — requires polars, pandas, or pyarrow; displays an orange Feather badge
Dictionary (column-oriented, dict[str, list]) — displays a gray Table badge
List of dictionaries (row-oriented, list[dict]) — displays a gray Table badge

For file-based inputs, pass a string or pathlib.Path object. The file extension is used to determine the format. Polars is preferred for loading when available; Pandas and PyArrow are used as fallbacks.

Examples

The simplest way to preview a table is to pass a Python dictionary:

from great_docs import tbl_preview

tbl_preview({"city": ["Tokyo", "Paris", "New York"], "population": [13960000, 2161000, 8336000]})

	city str	population i64
TableRows3Columns2
0	Tokyo	13960000
1	Paris	2161000
2	New York	8336000

The result is a styled HTML table with a header banner showing the row and column count, dtype labels beneath each column name, and row numbers on the left.

You can also pass a Polars DataFrame:

import polars as pl

df = pl.DataFrame({
    "product": ["Widget", "Gadget", "Gizmo", "Doohickey", "Thingamajig"],
    "category": ["Electronics", "Tools", "Kitchen", "Garden", "Office"],
    "price": [29.99, 49.50, 12.00, 8.75, 199.99],
    "in_stock": [True, False, True, True, False],
})

tbl_preview(df)

	product str	category str	price f64	in_stock bool
PolarsRows5Columns4
0	Widget	Electronics	29.99	True
1	Gadget	Tools	49.5	False
2	Gizmo	Kitchen	12	True
3	Doohickey	Garden	8.75	True
4	Thingamajig	Office	199.99	False

For large tables, only the first n_head= and last n_tail= rows are shown, separated by a blue divider line. Adjust the counts to show more or fewer rows:

tbl_preview(df, n_head=2, n_tail=1)

	product str	category str	price f64	in_stock bool
PolarsRows5Columns4
0	Widget	Electronics	29.99	True
1	Gadget	Tools	49.5	False
4	Thingamajig	Office	199.99	False

Use columns= to focus on specific columns in a wide dataset:

tbl_preview(df, columns=["product", "price"])

	product str	price f64
PolarsRows5Columns4
0	Widget	29.99
1	Gadget	49.5
2	Gizmo	12
3	Doohickey	8.75
4	Thingamajig	199.99

File paths work directly—no need to load the data yourself:

tbl_preview("assets/tbl-preview-data/students.csv")

	name str	subject str	score f64	grade str	passed bool
CSVRows10Columns5
0	Alice	Math	95.5	A	True
1	Bob	Science	82	B	True
2	Charlie	English	71.3	C	True
3	Diana	History	60	D	True
4	Eve	Art	55.8	F	False
5	Frank	Math	88.2	B+	True
6	Grace	Science	79.9	C+	True
7	Hank	English	91	A-	True
8	Iris	History	66.4	D+	True
9	Jack	Art	73.7	C	True

Add a caption to label the preview:

tbl_preview(df, caption="Product Catalog for Q1 2026")

	product str	category str	price f64	in_stock bool
PolarsRows5Columns4
Product Catalog for Q1 2026
0	Widget	Electronics	29.99	True
1	Gadget	Tools	49.5	False
2	Gizmo	Kitchen	12	True
3	Doohickey	Garden	8.75	True
4	Thingamajig	Office	199.99	False

For a minimal look, turn off the header banner, dtype labels, and row numbers:

tbl_preview(df, show_dimensions=False, show_dtypes=False, show_row_numbers=False)

product	category	price	in_stock
Widget	Electronics	29.99	True
Gadget	Tools	49.5	False
Gizmo	Kitchen	12	True
Doohickey	Garden	8.75	True
Thingamajig	Office	199.99	False

Parameters

Returns

Supported Input Data Types

Examples

See Also