Let’s use the exibble dataset for the next few examples, we’ll learn how to make simple gt tables with the gt() function. The most basic thing to do is to just use gt() with the dataset as the input.
exibble |>gt()
num
char
fctr
date
time
datetime
currency
row
group
1.111e-01
apricot
one
2015-01-15
13:35
2018-01-01 02:22
49.950
row_1
grp_a
2.222e+00
banana
two
2015-02-15
14:40
2018-02-02 14:33
17.950
row_2
grp_a
3.333e+01
coconut
three
2015-03-15
15:45
2018-03-03 03:44
1.390
row_3
grp_a
4.444e+02
durian
four
2015-04-15
16:50
2018-04-04 15:55
65100.000
row_4
grp_a
5.550e+03
NA
five
2015-05-15
17:55
2018-05-05 04:00
1325.810
row_5
grp_b
NA
fig
six
2015-06-15
NA
2018-06-06 16:11
13.255
row_6
grp_b
7.770e+05
grapefruit
seven
NA
19:10
2018-07-07 05:22
NA
row_7
grp_b
8.880e+06
honeydew
eight
2015-08-15
20:20
NA
0.440
row_8
grp_b
This dataset has the row and group columns. The former contains unique values that are ideal for labeling rows, and this often happens in what is called the ‘stub’ (a reserved area that serves to label rows). With the gt() function, we can immediately place the contents of the row column into the stub column. To do this, we use the rowname_col argument with the name of the column to use in quotes.
exibble |>gt(rowname_col ="row")
num
char
fctr
date
time
datetime
currency
group
row_1
1.111e-01
apricot
one
2015-01-15
13:35
2018-01-01 02:22
49.950
grp_a
row_2
2.222e+00
banana
two
2015-02-15
14:40
2018-02-02 14:33
17.950
grp_a
row_3
3.333e+01
coconut
three
2015-03-15
15:45
2018-03-03 03:44
1.390
grp_a
row_4
4.444e+02
durian
four
2015-04-15
16:50
2018-04-04 15:55
65100.000
grp_a
row_5
5.550e+03
NA
five
2015-05-15
17:55
2018-05-05 04:00
1325.810
grp_b
row_6
NA
fig
six
2015-06-15
NA
2018-06-06 16:11
13.255
grp_b
row_7
7.770e+05
grapefruit
seven
NA
19:10
2018-07-07 05:22
NA
grp_b
row_8
8.880e+06
honeydew
eight
2015-08-15
20:20
NA
0.440
grp_b
This sets up a table with a stub, the row labels are placed within the stub column, and a vertical dividing line has been placed on the right-hand side.
The group column can be used to divide the rows into discrete groups. Within that column, we see repetitions of the values grp_a and grp_b. These serve both as ID values and the initial label for the groups. With the groupname_col argument in gt(), we can set up the row groups immediately upon creation of the table.
If you’d rather perform the set up of row groups later (i.e., not in the gt() call), this is possible with tab_row_group() (and row_group_order() can help with the arrangement of row groups).
One more thing to consider with row groups is their layout. By default, row group labels reside in separate rows the appear above the group. However, we can use row_group_as_column = TRUE to put the row group labels within a secondary column within the table stub.
This could be done later if need be, and using tab_options(row_group.as_column = TRUE) would be the way to do it outside of the gt() call.
Some datasets have rownames built in; mtcars famously has the car model names as the rownames. To use those rownames as row labels in the stub, the rownames_to_stub = TRUE option will prove to be useful.
head(mtcars, 10) |>gt(rownames_to_stub =TRUE)
mpg
cyl
disp
hp
drat
wt
qsec
vs
am
gear
carb
Mazda RX4
21.0
6
160.0
110
3.90
2.620
16.46
0
1
4
4
Mazda RX4 Wag
21.0
6
160.0
110
3.90
2.875
17.02
0
1
4
4
Datsun 710
22.8
4
108.0
93
3.85
2.320
18.61
1
1
4
1
Hornet 4 Drive
21.4
6
258.0
110
3.08
3.215
19.44
1
0
3
1
Hornet Sportabout
18.7
8
360.0
175
3.15
3.440
17.02
0
0
3
2
Valiant
18.1
6
225.0
105
2.76
3.460
20.22
1
0
3
1
Duster 360
14.3
8
360.0
245
3.21
3.570
15.84
0
0
3
4
Merc 240D
24.4
4
146.7
62
3.69
3.190
20.00
1
0
4
2
Merc 230
22.8
4
140.8
95
3.92
3.150
22.90
1
0
4
2
Merc 280
19.2
6
167.6
123
3.92
3.440
18.30
1
0
4
4
By default, values in the body of a gt table (and their column labels) are automatically aligned. The alignment is governed by the types of values in a column. If you’d like to disable this form of auto-alignment, the auto_align = FALSE option can be taken.
What you’ll get from that is center-alignment of all table body values and all column labels. Note that row labels in the stub are still left-aligned; and auto_align has no effect on alignment within the table stub.
However which way you generate the initial gt table object, you can use it with a huge variety of functions in the package to further customize the presentation. Formatting body cells is commonly done with the family of formatting functions (e.g., fmt_number(), fmt_date(), etc.). The package supports formatting with internationalization (‘i18n’ features) and so locale-aware functions come with a locale argument. To avoid having to use that argument repeatedly, the gt() function has its own locale argument. Setting a locale in that will make it available globally. Here’s an example of how that works in practice when setting locale = "fr" in gt() and using formatting functions:
In this example, fmt_number() and fmt_date() understand that the locale for this table is "fr" (French), so the appropriate formatting for that locale is apparent in the num, currency, and date columns. However in fmt_datetime(), we explicitly use the "en" (English) locale. This overrides the "fr" default set for this table and the end result is dates formatted with the English locale in the datetime column.