cell_borders: Helper for defining custom borders for table cells

In gt: Easily Create Presentation-Ready Display Tables

Helper for defining custom borders for table cells

Description

cell_borders() is to be used with tab_style(), which itself allows for the setting of custom styles to one or more cells. Specifically, the call to cell_borders() should be bound to the styles argument of tab_style(). The sides argument is where we define which borders should be modified (e.g., "left", "right", etc.). With that selection, the color, style, and weight of the selected borders can then be modified.

Usage

cell_borders(sides = "all", color = "#000000", style = "solid", weight = px(1))

Arguments

sides	Border sides ⁠vector<character>⁠ // default: "all" The border sides to be modified. Options include "left", "right", "top", and "bottom". For all borders surrounding the selected cells, we can use the "all" option.
color	Border color ⁠scalar<character>|NULL⁠ // default: "#000000" The border color can be defined with a color name or with a hexadecimal color code. The default color value is "#000000" (black). Borders for any defined sides can be removed by supplying NULL here.
style	Border line style ⁠scalar<character>|NULL⁠ // default: "solid" The border style can be one of either "solid" (the default), "dashed", "dotted", "hidden", or "double". Borders for any defined sides can be removed by supplying NULL here.
weight	Border weight ⁠scalar<character>|NULL⁠ // default: px(1) The default value for weight is "1px" and higher values will become more visually prominent. Borders for any defined sides can be removed by supplying NULL to any of color, style, or weight.

Value

A list object of class cell_styles.

Examples

We can add horizontal border lines for all table body rows in a gt table based on the exibble dataset. For this, we need to use tab_style() (targeting all cells in the table body with cells_body()) in conjunction with cell_borders() in the style argument. Both top and bottom borders will be added as "solid" and "red" lines with a line width of 1.5 px.

exibble |>
  gt() |>
  tab_style(
    style = cell_borders(
      sides = c("top", "bottom"),
      color = "red",
      weight = px(1.5),
      style = "solid"
    ),
    locations = cells_body()
  )

It's possible to incorporate different horizontal and vertical ("left" and "right") borders at several different locations. This uses multiple cell_borders() and cells_body() calls within their own respective lists.

exibble |>
  gt() |>
  tab_style(
    style = list(
      cell_borders(
        sides = c("top", "bottom"),
        color = "#FF0000",
        weight = px(2)
      ),
      cell_borders(
        sides = c("left", "right"),
        color = "#0000FF",
        weight = px(2)
      )
    ),
    locations = list(
      cells_body(
        columns = num,
        rows = is.na(num)
      ),
      cells_body(
        columns = currency,
        rows = is.na(currency)
      )
    )
  )

Function ID

8-27

Function Introduced

v0.2.0.5 (March 31, 2020)

See Also

Other helper functions: adjust_luminance(), cell_fill(), cell_text(), currency(), default_fonts(), escape_latex(), from_column(), google_font(), gt_latex_dependencies(), html(), md(), nanoplot_options(), pct(), px(), random_id(), row_group(), stub(), system_fonts(), unit_conversion()

gt documentation built on April 12, 2025, 1:26 a.m.