Customizing How Your Tables Look

The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

tsg uses a style object (called a facade) to control how your tables look when exported — fonts, colours, borders, cell sizes, and more. You can:

The same style applies consistently to all output formats (Excel, HTML, PDF, Word).

Using a built-in style

The package ships with two named styles for Excel output. Pass one to write_xlsx() via the facade argument.

Style name	Description
`"default"`	Clean, neutral — used automatically when no style is specified
`"yolo"`	Bolder colours and heavier formatting

# Bold "yolo" style
person_record |>
  generate_frequency(sex) |>
  write_xlsx(path = "yolo.xlsx", facade = get_tsg_facade("yolo"))

# Explicitly use the default style (same as omitting the facade argument)
person_record |>
  generate_frequency(sex) |>
  write_xlsx(path = "default.xlsx", facade = get_tsg_facade("default"))

Tweaking a few settings with `add_facade()`

add_facade() lets you override individual style settings without replacing the whole style. Call it in your pipeline before write_*().

Style settings use a two-part name: which part of the table . what to change. For example:

header.bgFill — background colour of the column header
body.fontSize — font size of the data cells
table.offsetRow — blank rows above the table (Excel only)

person_record |>
  generate_frequency(sex) |>
  add_facade(
    table.offsetRow = 2,
    table.offsetCol = 1
  )
#> # A tibble: 3 × 3
#>   category   frequency percent
#>   <int+lbl>      <int>   <dbl>
#> 1 1 [Male]        1516    52.0
#> 2 2 [Female]      1402    48.0
#> 3 0 [Total]       2918   100

Common tweaks

person_record |>
  generate_crosstab(marital_status, sex) |>
  add_facade(
    # Move the table down 2 rows and right 1 column (Excel only)
    table.offsetRow        = 2,
    table.offsetCol        = 1,
    # Round numbers to 1 decimal place
    table.decimalPrecision = 1,
    # Make the last row (usually Total) bold
    table.lastRowBold      = TRUE,
    # Header background colour and white text
    header.bgFill          = "#003366",
    header.fontColour      = "#FFFFFF",
    header.textDecoration  = "bold",
    # Data cell font size
    body.fontSize          = 11
  ) |>
  write_xlsx(path = "styled-table.xlsx")

Good to know: A few settings only apply to Excel output (such as table.offsetRow, table.gridLines, and table.tabColour). They are harmlessly ignored when exporting to HTML, Word, or PDF — so you can attach them once and export to any format without changing anything.

Applying the same tweaks across formats

Once you attach style overrides with add_facade(), those overrides are carried with the table object and applied to whichever format you export to. You only need to style the table once.

styled_tbl <- person_record |>
  generate_frequency(sex) |>
  add_table_title("Distribution by Sex") |>
  add_source_note("Source: Survey 2024") |>
  add_facade(
    header.bgFill         = "#003366",
    header.fontColour     = "#FFFFFF",
    header.textDecoration = "bold",
    body.fontSize         = 11,
    table.lastRowBold     = TRUE
  )

write_xlsx(styled_tbl, path = "table.xlsx")
write_html(styled_tbl, path = "table.html")
write_pdf(styled_tbl,  path = "table.pdf")
write_docx(styled_tbl, path = "table.docx")

Making your own style file

For full control, generate a starter YAML file, edit it to your taste, and load it back in.

Step 1 — generate the template

generate_template("my-style.yaml", template = "facade")

Step 2 — edit the file

Open my-style.yaml in any text editor. It looks like this:

table.fontName: 'Arial'
table.fontSize: 12
table.offsetRow: 0
table.offsetCol: 0
table.decimalPrecision: 2
table.lastRowBold: false
table.width: 14

header.bgFill: ~          # ~ means "use the default"
header.fontColour: ~
header.textDecoration: ~
header.height: 28

body.fontSize: ~
body.bgFill: ~
body.numFmt: "###0"
body.height: 20

title.fontSize: 13
title.textDecoration: "bold"
title.height: 24

source_note.fontSize: 10
source_note.textDecoration: "italic"

Change any value you like. Use ~ to keep the built-in default for a setting.

Tip: get_tsg_facade() also accepts .json file paths if you prefer JSON over YAML.

Step 3 — use your style

my_style <- get_tsg_facade("my-style.yaml")

person_record |>
  generate_frequency(sex) |>
  write_xlsx(path = "custom-styled.xlsx", facade = my_style)

Programmatic style overrides

If you need to build style settings dynamically (for example, in a loop or from a config), use add_facade_alt(). It accepts a named list instead of individual named arguments.

overrides <- list(
  table.offsetRow   = 3,
  header.bgFill     = "#2E4057",
  header.fontColour = "#FFFFFF",
  body.fontSize     = 11
)

do.call(
  add_facade_alt,
  c(list(data = person_record |> generate_frequency(sex)), overrides)
)
#> # A tibble: 3 × 3
#>   category   frequency percent
#>   <int+lbl>      <int>   <dbl>
#> 1 1 [Male]        1516    52.0
#> 2 2 [Female]      1402    48.0
#> 3 0 [Total]       2918   100

Style property reference

The table below lists every setting supported by each section of the table.

Section	Properties
table	fontName, fontSize, fontColour, bgFill, fgFill, halign, valign, textDecoration, wrapText, indent, border, borderColour, borderStyle, width
title	fontName, fontSize, fontColour, bgFill, fgFill, halign, valign, textDecoration, wrapText, indent, border, borderColour, borderStyle, height
subtitle	fontName, fontSize, fontColour, bgFill, fgFill, halign, valign, textDecoration, wrapText, indent, border, borderColour, borderStyle, height
header	fontName, fontSize, fontColour, bgFill, fgFill, halign, valign, textDecoration, wrapText, indent, border, borderColour, borderStyle, height
spanner	fontName, fontSize, fontColour, bgFill, fgFill, halign, valign, textDecoration, wrapText, indent, border, borderColour, borderStyle, height
body	fontName, fontSize, fontColour, bgFill, fgFill, halign, valign, textDecoration, wrapText, indent, border, borderColour, borderStyle, numFmt, height
col_first	fontName, fontSize, fontColour, bgFill, fgFill, halign, valign, textDecoration, wrapText, indent, border, borderColour, borderStyle, numFmt, height, width
col_last	fontName, fontSize, fontColour, bgFill, fgFill, halign, valign, textDecoration, wrapText, indent, border, borderColour, borderStyle, numFmt, height, width
row_group	fontName, fontSize, fontColour, bgFill, fgFill, halign, valign, textDecoration, wrapText, indent, border, borderColour, borderStyle, height, width
sub_group	fontName, fontSize, fontColour, bgFill, fgFill, halign, valign, textDecoration, wrapText, indent, border, borderColour, borderStyle, height
source_note	fontName, fontSize, fontColour, bgFill, fgFill, halign, valign, textDecoration, wrapText, indent, border, borderColour, borderStyle, height
footnotes	fontName, fontSize, fontColour, bgFill, fgFill, halign, valign, textDecoration, wrapText, indent, border, borderColour, borderStyle, height

Table-level settings (full list)

Setting	What it does	Excel	HTML	Word
`table.fontName`	Default font family	✓	✓	✓
`table.fontSize`	Default font size	✓	✓	✓
`table.fontColour`	Default font colour	✓	✓	✓
`table.bgFill`	Table background colour	✓	✓	✓
`table.decimalPrecision`	Decimal places for numbers	✓	✓	✓
`table.decimalCols`	Which columns get decimal formatting	✓	✓	✓
`table.lastRowBold`	Make the last row bold	✓	✓	✓
`table.offsetRow`	Blank rows above the table	✓
`table.offsetCol`	Blank columns to the left	✓
`table.gridLines`	Show worksheet grid lines	✓
`table.tabColour`	Excel worksheet tab colour	✓
`table.locked`	Lock the worksheet	✓
`table.hidden`	Hide the worksheet	✓
`table.width`	Column width	✓
`table.widthOffset`	Extra width added to auto-sized columns	✓

Colour values

All fontColour, bgFill, and fgFill settings accept:

Hex colour codes: "#003366"
Named R colours: "navy"
~ (in YAML) or NULL (in R) to use the inherited default

Section names

Section	What it styles
`table`	Global table settings
`title`	Title row above the table
`subtitle`	Subtitle row
`header`	Column header row(s)
`spanner`	Grouped header rows in cross-tabulations
`body`	Data rows
`col_first`	First (category) column
`col_last`	Last column
`row_group`	Group header rows
`sub_group`	Sub-group rows
`source_note`	Source note row below the table
`footnotes`	Footnote rows
`border_header`	Border under the header
`border_outer`	Outer border around the table
`border_bottom`	Bottom border row height

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.

Customizing How Your Tables Look

Using a built-in style

Tweaking a few settings with add_facade()

Common tweaks

Applying the same tweaks across formats

Making your own style file

Step 1 — generate the template

Step 2 — edit the file

Step 3 — use your style

Programmatic style overrides

Style property reference

Table-level settings (full list)

Colour values

Section names

Tweaking a few settings with `add_facade()`