Add horizontal bars to the top of a gt table

Adds a row of horizontal color bars above a gt table from a vector of hex colors, optionally carrying an image and a line of text. The bars are attached as the table caption, so they sit above everything else.

Usage

gt_border_bars_top(
  gt_object,
  colors,
  bar_height = 10,
  bar_width = "100%",
  bar_align = "center",
  img = NULL,
  img_width = 30,
  img_height = 30,
  img_padding = 10,
  img_align = "right",
  text = NULL,
  text_weight = "bold",
  text_color = "#FFFFFF",
  text_size = 18,
  text_align = "left",
  text_padding = 10
)

Arguments

gt_object

A gt table object to modify.

colors

Character. Hex color codes, one per bar. When img or text is supplied only the first color is used.

bar_height

Numeric. The height of the bars in pixels. Defaults to 10.

bar_width

Character. The width of the bar block, as a CSS width. Defaults to "100%".

bar_align

Character. Alignment of the block when bar_width is under "100%". One of "left", "center", "right". Defaults to "center".

img

Optional. A URL for an image to render in the bar. It is decorative, so it carries an empty alt. Defaults to NULL.

img_width

Numeric. The image width in pixels. Defaults to 30.

img_height

Numeric. The image height in pixels. Defaults to 30.

img_padding

Numeric. Padding around the image in pixels, so it does not touch the edge. Defaults to 10.

img_align

Character. The side the image padding is applied to, "left" or "right"; any other value applies no padding. Defaults to "right".

text

Optional. Text to display in the bar. Defaults to NULL.

text_weight

Character. The font weight of the text. Defaults to "bold".

text_color

Character. The text color. Defaults to "#FFFFFF".

text_size

Numeric. The font size in pixels. Defaults to 18.

text_align

Character. The side the text padding is applied to, "left" or "right"; any other value applies no padding. Defaults to "left".

text_padding

Numeric. Padding around the text in pixels. Defaults to 10.

Value

Returns a modified gt table with a row of bars above it.

Details

The bars are added with gt::tab_caption(), and a table id is resolved or generated so scoped CSS can zero the caption padding. With neither img nor text, each entry in colors becomes its own full-width bar stacked in a block. When img or text is supplied, a single bar is drawn in the first color as a flex row with the text at one end and the image at the other. The text font is read from the table's title styling and imported as a Google Font, falling back to the inherited font when none is set, so it renders in an exported table.

Examples

library(gt)

afc_north <- subset(
  sdv_example_standings, division == "AFC North",
  c(team_name, wins:points_against)
)
gt(afc_north) |>
  gt_border_bars_top(c("#1B7837", "#FFFFFF", "#B2182B"))


  

  
team_name
      
wins
      
losses
      
ties
      
win_pct
      
points_for
      
points_against
    
Pittsburgh Steelers
10
7
0
0.588
397
387
Baltimore Ravens
8
9
0
0.471
424
398
Cincinnati Bengals
6
11
0
0.353
414
492
Cleveland Browns
5
12
0
0.294
279
379

# a single bar carrying a title
atlantic <- subset(
  sdv_example_standings, division == "Atlantic",
  c(team_name, wins, losses, win_pct:points_against)
)
gt(atlantic) |>
  gt_border_bars_top("#22223B", text = "Atlantic Division, 2025-26", bar_height = 34)


  
Atlantic Division, 2025-26

  
team_name
      
wins
      
losses
      
win_pct
      
points_for
      
points_against
    
Boston Celtics
56
26
0.683
9418
8787
New York Knicks
53
29
0.646
9549
9030
Toronto Raptors
46
36
0.561
9400
9168
Philadelphia 76ers
45
37
0.549
9502
9517
Brooklyn Nets
20
62
0.244
8686
9505