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:
add_facade(), orThe same style applies consistently to all output formats (Excel, HTML, PDF, Word).
The package ships with thirteen named styles. Pass a name to any
writer via the facade argument: a style looks the same in
Excel, HTML, PDF and Word.
| Style name | Description |
|---|---|
"default" |
Clean, neutral; used automatically when no style is specified |
"yolo" |
Bolder colours and heavier formatting |
"apa" |
APA style: horizontal rules only, no fills, Times New Roman |
"booktabs" |
Thick top and bottom rules, a thin rule under the header, nothing else |
"striped" |
Coloured header band and banded body rows |
"gridded" |
Thin lines around every cell and a grey header, as in statistical yearbooks |
"minimal" |
No borders or fills, light grey rules between rows; suits web and dashboards |
"financial" |
Dark blue header, thin grey grid and a bold last row, as in business reports |
"nyt" |
Editorial: bold header over a thick rule, no vertical lines, light banding |
"jama" |
Medical-journal: horizontal rules only, bold sans-serif header and first column |
"dark" |
Light text on a dark background |
"pastel" |
Soft blue header and group titles |
"census" |
Official statistics: grey header, bold group titles, small italic notes |
tbl <- person_record |>
generate_frequency(sex)
write_xlsx(tbl, path = "booktabs.xlsx", facade = "booktabs")
write_html(tbl, path = "booktabs.html", facade = "booktabs")
write_docx(tbl, path = "booktabs.docx", facade = "booktabs")
# The default style is used when you leave out `facade`
write_xlsx(tbl, path = "default.xlsx")Only "default" differs a little between formats (for
example, Word uses a smaller font). Every other style is laid over that
format’s default. Settings that only mean something in a spreadsheet,
such as row heights and column widths, are ignored outside Excel.
Here is each style in Excel (a screenshot of the sheet
write_xlsx() writes) and in HTML (built with
as_gt(), which returns the styled gt table for
your own Quarto or R Markdown documents):
defaultExcel
HTML
| Marital status by sex | |||||
| Source: person_record | |||||
yoloExcel
HTML
| Marital status by sex | |||||
| Source: person_record | |||||
apaExcel
HTML
| Marital status by sex | |||||
| Source: person_record | |||||
booktabsExcel
HTML
| Marital status by sex | |||||
| Source: person_record | |||||
stripedExcel
HTML
| Marital status by sex | |||||
| Source: person_record | |||||
griddedExcel
HTML
| Marital status by sex | |||||
| Source: person_record | |||||
minimalExcel
HTML
| Marital status by sex | |||||
| Source: person_record | |||||
financialExcel
HTML
| Marital status by sex | |||||
| Source: person_record | |||||
nytExcel
HTML
| Marital status by sex | |||||
| Source: person_record | |||||
jamaExcel
HTML
| Marital status by sex | |||||
| Source: person_record | |||||
darkExcel
HTML
| Marital status by sex | |||||
| Source: person_record | |||||
pastelExcel
HTML
| Marital status by sex | |||||
| Source: person_record | |||||
censusExcel
HTML
| Marital status by sex | |||||
| Source: person_record | |||||
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.fgFill: fill colour of the column headerbody.fontSize: font size of the data cellstable.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 100person_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.fgFill = "#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 mean something in a spreadsheet: row heights (
height), column widths (width,table.widthOffset),table.offsetRow,table.offsetCol,table.gridLines,table.tabColour,table.locked,table.hidden,indentandwrapText. HTML, Word and PDF ignore them, so you can attach them once and export to any format without changing anything.
Borders take three settings per part: border (which
sides: "top", "bottom", "left",
"right"), borderColour and
borderStyle. Border styles use the Excel names in every
format; HTML, PDF and Word draw the nearest line:
borderStyle |
HTML / PDF | Word |
|---|---|---|
"thin", "hair" |
1px solid | 0.75pt solid |
"medium" |
2px solid | 1.5pt solid |
"thick" |
3px solid | 2.25pt solid |
"dashed", "mediumDashed" |
1px / 2px dashed | 0.75pt / 1.5pt dashed |
"dotted" |
1px dotted | 0.75pt dotted |
"double" |
3px double | 2.25pt double |
"dashDot", "dashDotDot",
"slantDashDot" and their medium forms |
dashed | dashed |
The parts with borders are body (every data cell),
header (every header cell), spanner (the upper
header rows of a crosstab), border_header (the rule under
the header) and border_outer (the outline around header and
body). body.bandFill shades every other data row.
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.fgFill = "#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")For full control, generate a starter YAML file, edit it to your taste, and load it back in.
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.fgFill: ~ # ~ leaves the setting off
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. A setting set to ~ is turned
off; a setting you delete from the file comes from the default
facade.
Tip:
get_tsg_facade()also accepts.jsonfile paths if you prefer JSON over YAML.
If you need to build style settings dynamically (for example, in a
loop or from a config), keep them in a named list and pass it to
add_facade() with do.call(), or pass the list
as the facade of a writer.
overrides <- list(
table.offsetRow = 3,
header.fgFill = "#2E4057",
header.fontColour = "#FFFFFF",
body.fontSize = 11
)
do.call(
add_facade,
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 100The 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 |
| 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 | ✓ |
fgFill is the fill colour of a cell. bgFill
is the background of a fill pattern in Excel, so it shows only behind a
pattern; HTML and Word use it when fgFill is not set. All
fontColour, bgFill, and fgFill
settings accept:
"#003366""navy"~ (in YAML) or NULL (in R) to use the
inherited default| 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 |