Color and bold the tier column of a gt table

Fills the cells of a tier column by tier level and bolds them, pairing each level with a color. The remaining columns are rendered as images, since the intended layout is a tier list with logos or headshots ranked into colored bands.

Usage

gt_tiers(
  gt_object,
  levels,
  colors = NULL,
  style = "dark",
  img_height = "55px",
  tier_column = "tier",
  image_columns = NULL,
  alt = NULL
)

Arguments

gt_object

A gt table object to modify.

levels

Character. The tier levels, matching the values in the table's tier column. May instead be a single named vector of level = color, in which case colors is left unset. That is the same shape gt_legend_discrete() takes, so one object can drive both.

colors

Character. Hex color codes paired with levels, in the same order. Must be the same length as levels. Defaults to NULL, which requires levels to carry the colors as names.

style

Character. The color scheme, passed to gt_theme_tier(). Either "dark" for a near-black ground or "light" for a white one. Defaults to "dark".

img_height

Character. The height of the images rendered in the image columns, as a CSS size. Defaults to "55px".

tier_column

Character. The name of the column holding the tier levels. Defaults to "tier".

image_columns

Optional. The columns to render as images. When NULL, every column other than tier_column is rendered as images. Defaults to NULL.

alt

Optional. A function that takes the image paths or URLs and returns their alt text, one string per image, such as function(url) names_by_url[url]. Defaults to NULL, which names a team logo or wordmark the package knows (any mark in the logo archive, and the season logos season draws) by the team, and any other image by its file name without the extension.

Value

Returns a modified gt table with the tier column colored and bolded.

Details

The theme is applied once with gt_theme_tier(), the image columns are passed through gt::fmt_image() at img_height, and all column labels are cleared, so the input for those columns must be image paths or URLs. Each image gets its own alt text from alt, so a screen reader can tell the entries apart. The function then reduces over levels, and for each level fills the matching tier_column cells with the paired color and sets their text to black or white, whichever measures higher contrast against that fill, so each band keeps a legible label. Naming image_columns leaves the rest untouched, so a text column can sit alongside the images.

Examples

library(gt)

# the AFC's seven playoff seeds: the top seed's bye, then the wild-card round
afc <- subset(sdv_example_standings, conference == "AFC" & conference_rank <= 7)
afc <- afc[order(afc$conference_rank), ]
seeds <- data.frame(
  tier = ifelse(afc$conference_rank == 1, "Bye", "Wild card"),
  logo = sdv_logo_url(afc$team, "nfl")
)

# the logos are URLs, which the browser fetches when the table is shown
gt(seeds) |>
  gt_tiers(levels = c("Bye", "Wild card"), colors = c("#1B7837", "#B2182B"))


  

      

    
Bye
Wild card
Wild card
Wild card
Wild card
Wild card
Wild card