## tbl_preview() Generate a self-contained HTML table preview from almost any tabular data source. Usage ``` python 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()](tbl_preview.md#great_docs.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 `
` 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: ``` python from great_docs import tbl_preview tbl_preview({"city": ["Tokyo", "Paris", "New York"], "population": [13960000, 2161000, 8336000]}) ```
TableRows3Columns2
city str
population i64
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: ``` python 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) ```
PolarsRows5Columns4
product str
category str
price f64
in_stock bool
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: ``` python tbl_preview(df, n_head=2, n_tail=1) ```
PolarsRows5Columns4
product str
category str
price f64
in_stock bool
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: ``` python tbl_preview(df, columns=["product", "price"]) ```
PolarsRows5Columns4
product str
price f64
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: ``` python tbl_preview("assets/tbl-preview-data/students.csv") ```
CSVRows10Columns5
name str
subject str
score f64
grade str
passed bool
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: ``` python tbl_preview(df, caption="Product Catalog for Q1 2026") ```
PolarsRows5Columns4
Product Catalog for Q1 2026
product str
category str
price f64
in_stock bool
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: ``` python 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 | ## See Also [tbl_explorer()](tbl_explorer.md#great_docs.tbl_explorer) Launch an interactive table explorer for deeper data investigation.