GT.cols_reorder()

Reorder all columns in a specified order.

Usage

GT.cols_reorder(columns)

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.