GT.fmt_url()

Format values as URL links.

Usage

Source

GT.fmt_url(
    columns=None,
    rows=None,
    label=None,
    as_button=False,
    color="auto",
    show_underline="auto",
    button_fill="auto",
    button_width=None,
    button_outline=None,
    target="_blank",
)

With fmt_url(), input URL strings in the table body are transformed into HTML anchor elements (<a> tags). The URLs can be displayed as-is, with a static label, or with a label generated by a function. The links can also be styled as buttons with customizable colors and dimensions.

In LaTeX output, the links are written with the href command (so the hyperref package needs to be loaded) and the styling options only apply to HTML output.

Parameters

columns: SelectExpr = None

The columns to target. Can either be a single column name or a series of column names provided in a list.

rows: RowSelectExpr = None

In conjunction with columns=, we can specify which of their rows should undergo formatting. The default is all rows, resulting in all rows in targeted columns being formatted. Alternatively, we can supply a row index, a list of row indices, or (for Polars DataFrames) a Polars expression such as pl.col("x") > 0.

label: str | Callable[[str], str] | None = None

An optional label to use for the link. If a string is provided, it will be used as the visible text for all links. If a callable is provided, it will be called with the URL string and should return the display label.

as_button: bool = False

Should the link be styled as a button? By default this is False.

color: str = "auto"

The color of the link text. The default "auto" uses "#008B8B" (dark cyan) for regular links and "#FFFFFF" (white) for buttons. Any CSS color name or hex value can be used.

show_underline: str | bool = "auto"

Should the link be underlined? The default "auto" uses True for regular links and False for buttons. Set explicitly to True or False to override.

button_fill: str = "auto"

The background color for button-style links. The default "auto" uses "#4682B4" (steel blue). Only used when as_button=True.

button_width: str | None = None

The width of the button. Should be a CSS width string (e.g., "150px"). By default buttons size to their content.

button_outline: str | None = None

The CSS outline for the button (e.g., "2px solid #ccc"). By default, a light gray outline is automatically added when the button fill color is very light, and hidden otherwise.

target: str | None = "_blank"
The target attribute for the anchor element. Defaults to "_blank" to open links in a new tab. Set to None to open in the same tab.

Returns

GT
The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.

Examples

Using a subset of the towny dataset, let’s format the website column as URL links.

import polars as pl
from great_tables import GT, md, data

towny_top = (
    data.pl.towny
    .filter(pl.col("csd_type") == "city")
    .select("name", "website", "population_2021")
    .sort("population_2021", descending=True)
    .head(10)
)

(
    GT(towny_top)
    .tab_header(
        title=md("The 10 Largest Municipalities in `towny`"),
        subtitle="Population values taken from the 2021 census.",
    )
    .fmt_integer(columns="population_2021")
    .fmt_url(columns="website")
    .cols_label(
        name="Name",
        website="Site",
        population_2021="Population",
    )
)
The 10 Largest Municipalities in towny
Population values taken from the 2021 census.
Name Site Population
Toronto https://www.toronto.ca 2,794,356
Ottawa https://ottawa.ca 1,017,449
Mississauga https://www.mississauga.ca 717,961
Brampton https://www.brampton.ca 656,480
Hamilton https://www.hamilton.ca 569,353
London https://london.ca 422,324
Markham https://www.markham.ca 338,503
Vaughan https://www.vaughan.ca 323,103
Kitchener https://www.kitchener.ca 256,885
Windsor https://www.citywindsor.ca 229,660

We can use a static label and disable underlines for a cleaner look, merging the URL column into the name column.

(
    GT(towny_top)
    .tab_header(
        title=md("The 10 Largest Municipalities in `towny`"),
        subtitle="Population values taken from the 2021 census.",
    )
    .fmt_integer(columns="population_2021")
    .fmt_url(columns="website", label="site", show_underline=False)
    .cols_merge(columns=["name", "website"], pattern="{0} ({1})")
    .cols_label(name="Name", population_2021="Population")
)
The 10 Largest Municipalities in towny
Population values taken from the 2021 census.
Name Population
Toronto (site) 2,794,356
Ottawa (site) 1,017,449
Mississauga (site) 717,961
Brampton (site) 656,480
Hamilton (site) 569,353
London (site) 422,324
Markham (site) 338,503
Vaughan (site) 323,103
Kitchener (site) 256,885
Windsor (site) 229,660

Button-styled links can be created with as_button=True.

(
    GT(towny_top)
    .fmt_integer(columns="population_2021")
    .fmt_url(
        columns="website",
        label=lambda x: x.replace("https://", "").replace("www.", ""),
        as_button=True,
        button_fill="steelblue",
        button_width="150px",
    )
    .cols_label(
        name="Name",
        website="Website",
        population_2021="Population",
    )
)
Name Website Population
Toronto toronto.ca 2,794,356
Ottawa ottawa.ca 1,017,449
Mississauga mississauga.ca 717,961
Brampton brampton.ca 656,480
Hamilton hamilton.ca 569,353
London london.ca 422,324
Markham markham.ca 338,503
Vaughan vaughan.ca 323,103
Kitchener kitchener.ca 256,885
Windsor citywindsor.ca 229,660