GT.cols_reorder

GT.cols_reorder(self, columns)

Reorder all columns in a specified order.

The cols_reorder() method allows you to completely rearrange the column order of a table. Provide all column names in the exact order you want them to appear. This is useful when you need full control over the column layout and want to express the entire ordering in a single call, rather than using multiple cols_move(), cols_move_to_start(), or cols_move_to_end() calls.

Every column in the table must appear exactly once in the columns= list. If any columns are missing or extra names are provided, a ValueError will be raised.

Parameters

columns : SelectExpr

A list of all column names in the desired display order. This can be a list of column name strings or a column selection expression (e.g., Polars selectors). All columns in the table must be included exactly once.

Returns

: GT

The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.

Raises

: ValueError

If the provided columns do not match all columns in the table (e.g., missing columns, extra columns, or duplicates).

Examples

Let’s use a subset of columns from the exibble dataset to create a table.

from great_tables import GT
from great_tables.data import exibble

exibble_mini = exibble[["num", "char", "fctr", "date", "time"]]

GT(exibble_mini)
num char fctr date time
0.1111 apricot one 2015-01-15 13:35
2.222 banana two 2015-02-15 14:40
33.33 coconut three 2015-03-15 15:45
444.4 durian four 2015-04-15 16:50
5550.0 five 2015-05-15 17:55
fig six 2015-06-15
777000.0 grapefruit seven 19:10
8880000.0 honeydew eight 2015-08-15 20:20

Now, let’s reorder the columns so that fctr and date come first, followed by the remaining columns in a custom order:

(
    GT(exibble_mini)
    .cols_reorder(["fctr", "date", "time", "char", "num"])
)
fctr date time char num
one 2015-01-15 13:35 apricot 0.1111
two 2015-02-15 14:40 banana 2.222
three 2015-03-15 15:45 coconut 33.33
four 2015-04-15 16:50 durian 444.4
five 2015-05-15 17:55 5550.0
six 2015-06-15 fig
seven 19:10 grapefruit 777000.0
eight 2015-08-15 20:20 honeydew 8880000.0

For tables with many columns, you can use Python’s iterable unpacking to build the column list programmatically. Here we use the full exibble dataset (9 columns) and move fctr to the front while pushing num and char to the end—without typing every column name in between:

# Unpack the first three column names and capture all remaining ones in `rest`
# exibble.columns is: ["num", "char", "fctr", "date", "time", "datetime", "currency", "row", "group"]
num, char, fctr, *rest = exibble.columns

# Build the new order: fctr first, then all middle columns in their
# original order, and finally char and num moved to the end
(
    GT(exibble)
    .cols_reorder([fctr, *rest, char, num])
)
fctr date time datetime currency row group char num
one 2015-01-15 13:35 2018-01-01 02:22 49.95 row_1 grp_a apricot 0.1111
two 2015-02-15 14:40 2018-02-02 14:33 17.95 row_2 grp_a banana 2.222
three 2015-03-15 15:45 2018-03-03 03:44 1.39 row_3 grp_a coconut 33.33
four 2015-04-15 16:50 2018-04-04 15:55 65100.0 row_4 grp_a durian 444.4
five 2015-05-15 17:55 2018-05-05 04:00 1325.81 row_5 grp_b 5550.0
six 2015-06-15 2018-06-06 16:11 13.255 row_6 grp_b fig
seven 19:10 2018-07-07 05:22 row_7 grp_b grapefruit 777000.0
eight 2015-08-15 20:20 0.44 row_8 grp_b honeydew 8880000.0

This unpacking technique is especially handy for wide tables where you want to pin a few columns to the start or end without manually listing every column in between. The *rest variable automatically adapts if columns are added to or removed from the dataset, making your table code more resilient to upstream schema changes.