GT.cols_width

GT.cols_width(self, cases=None, **kwargs)

Set the widths of columns.

Manual specifications of column widths can be performed using the cols_width() method. We choose which columns get specific widths. This can be in units of pixels or as percentages. Width assignments are supplied inside of a dictionary where columns are the keys and the corresponding width is the value.

Parameters

cases : dict[str, str] | None = None

A dictionary where the keys are column names and the values are the widths. Widths can be specified in pixels (e.g., "50px") or as percentages (e.g., "20%").

****kwargs** : str = {}

Keyword arguments to specify column widths. Each keyword corresponds to a column name, with its value indicating the width in pixels or percentages.

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.

Examples

Let’s use select columns from the exibble dataset to create a new table. We can specify the widths of columns with cols_width(). This is done by specifying the exact widths for table columns in a dictionary. In this example, we’ll set the width of the num column to "150px", the char column to "100px", the date column to "300px". All other columns won’t be affected (their widths will be automatically set by their content).

from great_tables import GT, exibble

exibble_mini = exibble[["num", "char", "date", "datetime", "row"]].head(5)

(
    GT(exibble_mini)
    .cols_width(
        cases={
            "num": "150px",
            "char": "100px",
            "date": "300px"
        }
    )
)

num	char	date	datetime	row
0.1111	apricot	2015-01-15	2018-01-01 02:22	row_1
2.222	banana	2015-02-15	2018-02-02 14:33	row_2
33.33	coconut	2015-03-15	2018-03-03 03:44	row_3
444.4	durian	2015-04-15	2018-04-04 15:55	row_4
5550.0		2015-05-15	2018-05-05 04:00	row_5

We can also specify the widths of columns as percentages. In this example, we’ll set the width of the num column to "20%", the char column to "10%", and the date column to "30%". Note that the percentages are relative and don’t need to sum to 100%.

(
    GT(exibble_mini)
    .cols_width(
        cases={
            "num": "20%",
            "char": "10%",
            "date": "30%"
        }
    )
)

num	char	date	datetime	row
0.1111	apricot	2015-01-15	2018-01-01 02:22	row_1
2.222	banana	2015-02-15	2018-02-02 14:33	row_2
33.33	coconut	2015-03-15	2018-03-03 03:44	row_3
444.4	durian	2015-04-15	2018-04-04 15:55	row_4
5550.0		2015-05-15	2018-05-05 04:00	row_5

We can also mix and match pixel and percentage widths. In this example, we’ll set the width of the num column to "150px", the char column to "10%", and the date column to "30%".

(
    GT(exibble_mini)
    .cols_width(
        cases={
            "num": "150px",
            "char": "10%",
            "date": "30%"
        }
    )
)

num	char	date	datetime	row
0.1111	apricot	2015-01-15	2018-01-01 02:22	row_1
2.222	banana	2015-02-15	2018-02-02 14:33	row_2
33.33	coconut	2015-03-15	2018-03-03 03:44	row_3
444.4	durian	2015-04-15	2018-04-04 15:55	row_4
5550.0		2015-05-15	2018-05-05 04:00	row_5

If we set the width of all columns, the table will be forced to use the specified widths (i.e., a column width less than the content width will be honored). In this next example, we’ll set widths for all columns. This is a good way to ensure that the widths you specify are fully respected (and not overridden by automatic width calculations).

(
    GT(exibble_mini)
    .cols_width(
        cases={
            "num": "30px",
            "char": "100px",
            "date": "100px",
            "datetime": "200px",
            "row": "50px"
        }
    )
)

num	char	date	datetime	row
0.1111	apricot	2015-01-15	2018-01-01 02:22	row_1
2.222	banana	2015-02-15	2018-02-02 14:33	row_2
33.33	coconut	2015-03-15	2018-03-03 03:44	row_3
444.4	durian	2015-04-15	2018-04-04 15:55	row_4
5550.0		2015-05-15	2018-05-05 04:00	row_5

Notice that in the above example, the num column is very small (only 30px) and the content overflows. When not specifying the width of all columns, the table will automatically adjust the column widths based on the content (and you wouldn’t get the overflowing behavior seen in the previous example).