Skip to contents

Focus on rows of a gt table by dimming the rest

Source: R/gt_spotlight.R
gt_spotlight.Rd

Emphasizes one or more rows and mutes everything else. gtExtras::gt_highlight_rows() makes a row louder; this leaves it as the only row at full strength.

Usage

gt_spotlight(
  gt_object,
  rows,
  columns = gt::everything(),
  fill = NULL,
  text_color = NULL,
  bold = TRUE,
  accent_color = NULL,
  accent_width = 4,
  accent_column = NULL,
  dim_color = "auto",
  if_none = c("warn", "dim", "ignore")
)

Arguments

gt_object

A gt table object to modify.

rows

The rows to focus on. Either an expression evaluated against the table's data, such as cyl == 8, or a numeric vector of row indices.

columns

The columns the spotlight covers. Cells outside this selection are dimmed, in the focused rows as well as the others, so only the selected cells are left at full strength. Defaults to all of them, which lights the whole row.

fill

Optional. A hex color for the fill behind the focused rows. Defaults to NULL.

text_color

Optional. A hex color for the text of the focused rows. Defaults to NULL.

bold

Logical. Should the focused rows be bolded? Defaults to TRUE.

accent_color

Optional. A color for a bar drawn on the left edge of the focused rows. Supplying one is what turns the bar on, the same way fill and text_color work. Defaults to NULL, no bar.

accent_width

Numeric. The width of that bar in pixels, used only when accent_color is given. Defaults to 4.

accent_column

The column to draw the bar against, on its left edge. If NULL, the leftmost rendered column is used, which is what marks the start of the row. Name a column when the row you are lighting sits elsewhere, as with the second block of a gt_snake() table. More than one may be given, which draws a bar against each. Defaults to NULL.

dim_color

Character. The text color applied to every other row. "auto", the default, blends the table's text toward its background until it sits just above 4.5:1 contrast against it (WCAG AA for text), so the rows read as muted rather than disabled, on a light or a dark theme. Apply the theme first: the background is read from the table as set so far. Pass a color to choose it yourself, or NULL to leave the other rows alone, emphasizing without dimming.

if_none

Character. What to do when rows matches nothing. "warn" leaves the table alone and says so. "dim" dims the whole table, which is what you want when several tables are laid out together with gt_grid() and the highlighted row lives in only one of them. "ignore" leaves it alone silently. Defaults to "warn".

Value

Returns a modified gt table with the chosen rows emphasized.

Details

Rows can be given as a filtering expression evaluated against the underlying data, or as plain row numbers.

See also

gt_cutline() for marking a threshold rather than a row.

Examples

library(gt)

nfc <- subset(
  sdv_example_standings, division %in% c("NFC North", "NFC West"),
  c(team_name, wins, losses, conference_rank)
)

# by expression: the playoff seeds
gt(nfc) |> gt_spotlight(rows = conference_rank <= 7)



  
team_name
      wins
      losses
      conference_rank
    
Chicago Bears
11
6
2
Green Bay Packers
9
7
7
Minnesota Vikings
9
8
8
Detroit Lions
9
8
9
Seattle Seahawks
14
3
1
Los Angeles Rams
12
5
5
San Francisco 49ers
12
5
6
Arizona Cardinals
3
14
16

# by position, with an accent bar
gt(nfc) |>
  gt_spotlight(rows = 2, accent_color = "#0054AD", fill = "#EEF3FA")



  
team_name
      wins
      losses
      conference_rank
    
Chicago Bears
11
6
2
Green Bay Packers
9
7
7
Minnesota Vikings
9
8
8
Detroit Lions
9
8
9
Seattle Seahawks
14
3
1
Los Angeles Rams
12
5
5
San Francisco 49ers
12
5
6
Arizona Cardinals
3
14
16

# narrowing the spotlight to some columns dims the rest of the row too
gt(nfc) |> gt_spotlight(wins:losses, rows = 3, accent_color = "darkblue")



  
team_name
      wins
      losses
      conference_rank
    
Chicago Bears
11
6
2
Green Bay Packers
9
7
7
Minnesota Vikings
9
8
8
Detroit Lions
9
8
9
Seattle Seahawks
14
3
1
Los Angeles Rams
12
5
5
San Francisco 49ers
12
5
6
Arizona Cardinals
3
14
16

# put the bar somewhere other than the first column
gt(nfc) |>
  gt_spotlight(losses, rows = 3, accent_color = "darkblue", accent_column = losses)



  
team_name
      wins
      losses
      conference_rank
    
Chicago Bears
11
6
2
Green Bay Packers
9
7
7
Minnesota Vikings
9
8
8
Detroit Lions
9
8
9
Seattle Seahawks
14
3
1
Los Angeles Rams
12
5
5
San Francisco 49ers
12
5
6
Arizona Cardinals
3
14
16

# across several tables: blocks without a 12-win team dim rather than stay lit
chunks <- split(nfc, ceiling(seq_len(nrow(nfc)) / 4))
tbls <- lapply(chunks, function(x) {
  gt(x) |> gt_spotlight(rows = wins >= 12, if_none = "dim")
})
gt_grid(tbls, ncol = 2)


  

    

      
team_name
      wins
      losses
      conference_rank
    
Chicago Bears
11
6
2
Green Bay Packers
9
7
7
Minnesota Vikings
9
8
8
Detroit Lions
9
8
9

  

  

    

      
team_name
      wins
      losses
      conference_rank
    
Seattle Seahawks
14
3
1
Los Angeles Rams
12
5
5
San Francisco 49ers
12
5
6
Arizona Cardinals
3
14
16