GT.tab_options

GT.tab_options(self, container_width=None, container_height=None, container_overflow_x=None, container_overflow_y=None, table_width=None, table_layout=None, table_margin_left=None, table_margin_right=None, table_background_color=None, table_font_names=None, table_font_size=None, table_font_weight=None, table_font_style=None, table_font_color=None, table_font_color_light=None, table_border_top_style=None, table_border_top_width=None, table_border_top_color=None, table_border_bottom_style=None, table_border_bottom_width=None, table_border_bottom_color=None, table_border_left_style=None, table_border_left_width=None, table_border_left_color=None, table_border_right_style=None, table_border_right_width=None, table_border_right_color=None, heading_background_color=None, heading_align=None, heading_title_font_size=None, heading_title_font_weight=None, heading_subtitle_font_size=None, heading_subtitle_font_weight=None, heading_padding=None, heading_padding_horizontal=None, heading_border_bottom_style=None, heading_border_bottom_width=None, heading_border_bottom_color=None, heading_border_lr_style=None, heading_border_lr_width=None, heading_border_lr_color=None, column_labels_background_color=None, column_labels_font_size=None, column_labels_font_weight=None, column_labels_text_transform=None, column_labels_padding=None, column_labels_padding_horizontal=None, column_labels_vlines_style=None, column_labels_vlines_width=None, column_labels_vlines_color=None, column_labels_border_top_style=None, column_labels_border_top_width=None, column_labels_border_top_color=None, column_labels_border_bottom_style=None, column_labels_border_bottom_width=None, column_labels_border_bottom_color=None, column_labels_border_lr_style=None, column_labels_border_lr_width=None, column_labels_border_lr_color=None, column_labels_hidden=None, row_group_background_color=None, row_group_font_size=None, row_group_font_weight=None, row_group_text_transform=None, row_group_padding=None, row_group_padding_horizontal=None, row_group_border_top_style=None, row_group_border_top_width=None, row_group_border_top_color=None, row_group_border_bottom_style=None, row_group_border_bottom_width=None, row_group_border_bottom_color=None, row_group_border_left_style=None, row_group_border_left_width=None, row_group_border_left_color=None, row_group_border_right_style=None, row_group_border_right_width=None, row_group_border_right_color=None, row_group_as_column=None, table_body_hlines_style=None, table_body_hlines_width=None, table_body_hlines_color=None, table_body_vlines_style=None, table_body_vlines_width=None, table_body_vlines_color=None, table_body_border_top_style=None, table_body_border_top_width=None, table_body_border_top_color=None, table_body_border_bottom_style=None, table_body_border_bottom_width=None, table_body_border_bottom_color=None, stub_background_color=None, stub_font_size=None, stub_font_weight=None, stub_text_transform=None, stub_border_style=None, stub_border_width=None, stub_border_color=None, stub_row_group_font_size=None, stub_row_group_font_weight=None, stub_row_group_text_transform=None, stub_row_group_border_style=None, stub_row_group_border_width=None, stub_row_group_border_color=None, data_row_padding=None, data_row_padding_horizontal=None, source_notes_background_color=None, source_notes_font_size=None, source_notes_padding=None, source_notes_padding_horizontal=None, source_notes_border_bottom_style=None, source_notes_border_bottom_width=None, source_notes_border_bottom_color=None, source_notes_border_lr_style=None, source_notes_border_lr_width=None, source_notes_border_lr_color=None, source_notes_multiline=None, source_notes_sep=None)

Modify the table output options.

Modify the options available in a table. These options are named by the components, the subcomponents, and the element that can adjusted.

Parameters

Name	Type	Description	Default
`container_width`	`str` \| None	The width of the table’s container. Can be specified as a single-length character with units of pixels or as a percentage. If provided as a scalar numeric value, it is assumed that the value is given in units of pixels.	`None`
`container_height`	`str` \| None	The height of the table’s container.	`None`
`container_overflow_x`	`str` \| None	An option to enable scrolling in the horizontal direction when the table content overflows the container dimensions. Using `True` (the default) means that horizontal scrolling is enabled to view the entire table in those directions. With `False`, the table may be clipped if the table width or height exceeds the `container_width`.	`None`
`container_overflow_y`	`str` \| None	An option to enable scrolling in the vertical direction when the table content overflows. Same rules apply as for `container_overflow_x`; the dependency here is that of the table height (`container_height`).	`None`
`table_width`	`str` \| None	The width of the table. Can be specified as a string with units of pixels or as a percentage. If provided as a numeric value, it is assumed that the value is given in units of pixels.	`None`
`table_layout`	`str` \| None	The value for the `table-layout` CSS style in the HTML output context. By default, this is `"fixed"` but another valid option is `"auto"`.	`None`
`table_margin_left`	`str` \| None	The size of the margins on the left of the table within the container. Can be specified as a single-length value with units of pixels or as a percentage. If provided as a numeric value, it is assumed that the value is given in units of pixels. Using `table_margin_left` will overwrite any values set by `table_align`.	`None`
`table_margin_right`	`str` \| None	The size of the margins on the right of the table within the container. Same rules apply as for `table_margin_left`. Using `table_margin_right` will overwrite any values set by `table_align`.	`None`
`table_background_color`	`str` \| None	The background color for the table. A color name or a hexadecimal color code should be provided.	`None`
`table_font_names`	`str` \| `list`[`str`] \| None	The names of the fonts used for the table. This should be provided as a list of font names. If the first font isn’t available, then the next font is tried (and so on).	`None`
`table_font_size`	`str` \| None	The font size for the table. Can be specified as a string with units of pixels or as a percentage. If provided as a numeric value, it is assumed that the value is given in units of pixels.	`None`
`table_font_weight`	`str` \| `int` \| `float` \| None	The font weight of the table. Can be a text-based keyword such as `"normal"`, `"bold"`, `"lighter"`, `"bolder"`, or, a numeric value between `1` and `1000`, inclusive. Note that only variable fonts may support the numeric mapping of weight.	`None`
`table_font_style`	`str` \| None	The font style for the table. Can be one of either `"normal"`, `"italic"`, or `"oblique"`.	`None`
`table_font_color`	`str` \| None	The text color used throughout the table. A color name or a hexadecimal color code should be provided.	`None`
`table_font_color_light`	`str` \| None	The text color used throughout the table when the background color is dark. A color name or a hexadecimal color code should be provided.	`None`
`table_border_top_style`	`str` \| None	The style of the table’s absolute top border. Can be one of either `"solid"`, `"dotted"`, `"dashed"`, `"double"`, `"groove"`, `"ridge"`, `"inset"`, or `"outset"`.	`None`
`table_border_top_width`	`str` \| None	The width of the table’s absolute top border. Can be specified as a string with units of pixels or as a percentage. If provided as a numeric value, it is assumed that the value is given in units of pixels.	`None`
`table_border_top_color`	`str` \| None	The color of the table’s absolute top border. A color name or a hexadecimal color code should be provided.	`None`
`table_border_bottom_style`	`str` \| None	The style of the table’s absolute bottom border.	`None`
`table_border_bottom_width`	`str` \| None	The width of the table’s absolute bottom border.	`None`
`table_border_bottom_color`	`str` \| None	The color of the table’s absolute bottom border.	`None`
`table_border_left_style`	`str` \| None	The style of the table’s absolute left border.	`None`
`table_border_left_width`	`str` \| None	The width of the table’s absolute left border.	`None`
`table_border_left_color`	`str` \| None	The color of the table’s absolute left border.	`None`
`table_border_right_style`	`str` \| None	The style of the table’s absolute right border.	`None`
`table_border_right_width`	`str` \| None	The width of the table’s absolute right border.	`None`
`table_border_right_color`	`str` \| None	The color of the table’s absolute right border.	`None`
`heading_background_color`	`str` \| None	The background color for the heading. A color name or a hexadecimal color code should be provided.	`None`
`heading_align`	`str` \| None	Controls the horizontal alignment of the heading title and subtitle. We can either use `"center"`, `"left"`, or `"right"`.	`None`
`heading_title_font_size`	`str` \| None	The font size for the heading title element.	`None`
`heading_title_font_weight`	`str` \| `int` \| `float` \| None	The font weight of the heading title.	`None`
`heading_subtitle_font_size`	`str` \| None	The font size for the heading subtitle element.	`None`
`heading_subtitle_font_weight`	`str` \| `int` \| `float` \| None	The font weight of the heading subtitle.	`None`
`heading_padding`	`str` \| None	The amount of vertical padding to incorporate in the `heading` (title and subtitle). Can be specified as a string with units of pixels or as a percentage. If provided as a numeric value, it is assumed that the value is given in units of pixels.	`None`
`heading_padding_horizontal`	`str` \| None	The amount of horizontal padding to incorporate in the `heading` (title and subtitle). Can be specified as a string with units of pixels or as a percentage. If provided as a numeric value, it is assumed that the value is given in units of pixels.	`None`
`heading_border_bottom_style`	`str` \| None	The style of the header’s bottom border.	`None`
`heading_border_bottom_width`	`str` \| None	The width of the header’s bottom border. If the `width` of this border is larger, then it will be the visible border.	`None`
`heading_border_bottom_color`	`str` \| None	The color of the header’s bottom border.	`None`
`heading_border_lr_style`	`str` \| None	The style of the left and right borders of the `heading` location.	`None`
`heading_border_lr_width`	`str` \| None	The width of the left and right borders of the `heading` location. If the `width` of this border is larger, then it will be the visible border.	`None`
`heading_border_lr_color`	`str` \| None	The color of the left and right borders of the `heading` location.	`None`
`column_labels_background_color`	`str` \| None	The background color for the column labels. A color name or a hexadecimal color code should be provided.	`None`
`column_labels_font_size`	`str` \| None	The font size to use for all column labels.	`None`
`column_labels_font_weight`	`str` \| `int` \| `float` \| None	The font weight of the table’s column labels.	`None`
`column_labels_text_transform`	`str` \| None	The text transformation for the column labels. Either of the `"uppercase"`, `"lowercase"`, or `"capitalize"` keywords can be used.	`None`
`column_labels_padding`	`str` \| None	The amount of vertical padding to incorporate in the `column_labels` (this includes the column spanners).	`None`
`column_labels_padding_horizontal`	`str` \| None	The amount of horizontal padding to incorporate in the `column_labels` (this includes the column spanners).	`None`
`column_labels_vlines_style`	`str` \| None	The style of all vertical lines (‘vlines’) of the `column_labels`.	`None`
`column_labels_vlines_width`	`str` \| None	The width of all vertical lines (‘vlines’) of the `column_labels`.	`None`
`column_labels_vlines_color`	`str` \| None	The color of all vertical lines (‘vlines’) of the `column_labels`.	`None`
`column_labels_border_top_style`	`str` \| None	The style of the top border of the `column_labels` location.	`None`
`column_labels_border_top_width`	`str` \| None	The width of the top border of the `column_labels` location. If the `width` of this border is larger, then it will be the visible border.	`None`
`column_labels_border_top_color`	`str` \| None	The color of the top border of the `column_labels` location.	`None`
`column_labels_border_bottom_style`	`str` \| None	The style of the bottom border of the `column_labels` location.	`None`
`column_labels_border_bottom_width`	`str` \| None	The width of the bottom border of the `column_labels` location. If the `width` of this border is larger, then it will be the visible border.	`None`
`column_labels_border_bottom_color`	`str` \| None	The color of the bottom border of the `column_labels` location.	`None`
`column_labels_border_lr_style`	`str` \| None	The style of the left and right borders of the `column_labels` location.	`None`
`column_labels_border_lr_width`	`str` \| None	The width of the left and right borders of the `column_labels` location. If the `width` of this border is larger, then it will be the visible border.	`None`
`column_labels_border_lr_color`	`str` \| None	The color of the left and right borders of the `column_labels` location.	`None`
`column_labels_hidden`	`bool` \| None	An option to hide the column labels. If providing `True` then the entire `column_labels` location won’t be seen and the table header (if present) will collapse downward.	`None`
`row_group_background_color`	`str` \| None	The background color for the row group labels. A color name or a hexadecimal color code should be provided.	`None`
`row_group_font_weight`	`str` \| `int` \| `float` \| None	The font weight for all row group labels present in the table.	`None`
`row_group_font_size`	`str` \| None	The font size to use for all row group labels.	`None`
`row_group_padding`	`str` \| None	The amount of vertical padding to incorporate in the row group labels.	`None`
`row_group_border_top_style`	`str` \| None	The style of the top border of the `row_group` location.	`None`
`row_group_border_top_width`	`str` \| None	The width of the top border of the `row_group` location. If the `width` of this border is larger, then it will be the visible border.	`None`
`row_group_border_top_color`	`str` \| None	The color of the top border of the `row_group` location.	`None`
`row_group_border_bottom_style`	`str` \| None	The style of the bottom border of the `row_group` location.	`None`
`row_group_border_bottom_width`	`str` \| None	The width of the bottom border of the `row_group` location. If the `width` of this border is larger, then it will be the visible border.	`None`
`row_group_border_bottom_color`	`str` \| None	The color of the bottom border of the `row_group` location.	`None`
`row_group_border_left_style`	`str` \| None	The style of the left border of the `row_group` location.	`None`
`row_group_border_left_width`	`str` \| None	The width of the left border of the `row_group` location. If the `width` of this border is larger, then it will be the visible border.	`None`
`row_group_border_left_color`	`str` \| None	The color of the left border of the `row_group` location.	`None`
`row_group_border_right_style`	`str` \| None	The style of the right border of the `row_group` location.	`None`
`row_group_border_right_width`	`str` \| None	The width of the right border of the `row_group` location. If the `width` of this border is	`None`
`row_group_border_right_color`	`str` \| None	The color of the right border of the `row_group` location.	`None`
`row_group_as_column`	`bool` \| None	An option to render the row group labels as a column. If `True`, then the row group labels will be rendered as a column to the left of the table body. If `False`, then the row group labels will be rendered as a separate row above the grouping of rows.	`None`
`table_body_hlines_style`	`str` \| None	The style of all horizontal lines (‘hlines’) in the `table_body`.	`None`
`table_body_hlines_width`	`str` \| None	The width of all horizontal lines (‘hlines’) in the `table_body`.	`None`
`table_body_hlines_color`	`str` \| None	The color of all horizontal lines (‘hlines’) in the `table_body`.	`None`
`table_body_vlines_style`	`str` \| None	The style of all vertical lines (‘vlines’) in the `table_body`.	`None`
`table_body_vlines_width`	`str` \| None	The width of all vertical lines (‘vlines’) in the `table_body`.	`None`
`table_body_vlines_color`	`str` \| None	The color of all vertical lines (‘vlines’) in the `table_body`.	`None`
`table_body_border_top_style`	`str` \| None	The style of the top border of the `table_body` location.	`None`
`table_body_border_top_width`	`str` \| None	The width of the top border of the `table_body` location. If the `width` of this border is larger, then it will be the visible border.	`None`
`table_body_border_top_color`	`str` \| None	The color of the top border of the `table_body` location.	`None`
`table_body_border_bottom_style`	`str` \| None	The style of the bottom border of the `table_body` location.	`None`
`table_body_border_bottom_width`	`str` \| None	The width of the bottom border of the `table_body` location. If the `width` of this border	`None`
`table_body_border_bottom_color`	`str` \| None	The color of the bottom border of the `table_body` location.	`None`
`stub_background_color`	`str` \| None	The background color for the stub. A color name or a hexadecimal color code should be provided.	`None`
`stub_font_size`	`str` \| None	The font size to use for all row labels present in the table stub.	`None`
`stub_font_weight`	`str` \| `int` \| `float` \| None	The font weight for all row labels present in the table stub.	`None`
`stub_text_transform`	`str` \| None	The text transformation for the row labels present in the table stub.	`None`
`stub_border_style`	`str` \| None	The style of the vertical border of the table stub.	`None`
`stub_border_width`	`str` \| None	The width of the vertical border of the table stub.	`None`
`stub_border_color`	`str` \| None	The color of the vertical border of the table stub.	`None`
`stub_row_group_font_size`	`str` \| None	The font size for the row group column in the stub.	`None`
`stub_row_group_font_weight`	`str` \| `int` \| `float` \| None	The font weight for the row group column in the stub.	`None`
`stub_row_group_text_transform`	`str` \| None	The text transformation for the row group column in the stub.	`None`
`stub_row_group_border_style`	`str` \| None	The style of the vertical border of the row group column in the stub.	`None`
`stub_row_group_border_width`	`str` \| None	The width of the vertical border of the row group column in the stub.	`None`
`stub_row_group_border_color`	`str` \| None	The color of the vertical border of the row group column in the stub.	`None`
`data_row_padding`	`str` \| None	The amount of vertical padding to incorporate in the body/stub rows.	`None`
`data_row_padding_horizontal`	`str` \| None	The amount of horizontal padding to incorporate in the body/stub rows.	`None`
`source_notes_background_color`	`str` \| None	The background color for the source notes. A color name or a hexadecimal color code should be provided.	`None`
`source_notes_font_size`	`str` \| None	The font size to use for all source note text.	`None`
`source_notes_padding`	`str` \| None	The amount of vertical padding to incorporate in the source notes.	`None`
`source_notes_padding_horizontal`	`str` \| None	The amount of horizontal padding to incorporate in the source notes.	`None`
`source_notes_multiline`	`bool` \| None	An option to either put source notes in separate lines (the default, or `True`) or render them as a continuous line of text with `source_notes_sep` providing the separator (by default `" "`) between notes.	`None`
`source_notes_sep`	`str` \| None	The separating characters between adjacent source notes when rendered as a continuous line of text (when `source_notes_multiline` is `False`). The default value is a single space character (`" "`).	`None`
`source_notes_border_bottom_style`	`str` \| None	The style of the bottom border of the `source_notes` location.	`None`
`source_notes_border_bottom_width`	`str` \| None	The width of the bottom border of the `source_notes` location. If the `width` of this border is larger, then it will be the visible border.	`None`
`source_notes_border_bottom_color`	`str` \| None	The color of the bottom border of the `source_notes` location.	`None`
`source_notes_border_lr_style`	`str` \| None	The style of the left and right borders of the `source_notes` location.	`None`
`source_notes_border_lr_width`	`str` \| None	The width of the left and right borders of the `source_notes` location. If the `width` of this border is larger, then it will be the visible border.	`None`
`source_notes_border_lr_color`	`str` \| None	The color of the left and right borders of the `source_notes` location.	`None`

Returns

Type	Description
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

Using select columns from the exibble dataset, let’s create a new table with a number of table components added. We can use this object going forward to demonstrate some of the features available in the tab_options() method.

from great_tables import GT, exibble, md

gt_tbl = (
  GT(
    exibble[["num", "char", "currency", "row", "group"]],
    rowname_col="row",
    groupname_col="group"
  )
  .tab_header(
    title=md("Data listing from **exibble**"),
    subtitle=md("`exibble` is a **Great Tables** dataset.")
  )
  .fmt_number(columns="num")
  .fmt_currency(columns="currency")
  .tab_source_note(source_note="This is only a subset of the dataset.")
)

gt_tbl

	num	char	currency
Data listing from exibble
`exibble` is a Great Tables dataset.
grp_a
row_1	0.11	apricot	$49.95
row_2	2.22	banana	$17.95
row_3	33.33	coconut	$1.39
row_4	444.40	durian	$65,100.00
grp_b
row_5	5,550.00		$1,325.81
row_6		fig	$13.26
row_7	777,000.00	grapefruit
row_8	8,880,000.00	honeydew	$0.44
This is only a subset of the dataset.

We can modify the table width to be set as "100%“. In effect, this spans the table to entirely fill the content width area. This is done with the table_width option.

gt_tbl.tab_options(table_width="100%")

	num	char	currency
Data listing from exibble
`exibble` is a Great Tables dataset.
grp_a
row_1	0.11	apricot	$49.95
row_2	2.22	banana	$17.95
row_3	33.33	coconut	$1.39
row_4	444.40	durian	$65,100.00
grp_b
row_5	5,550.00		$1,325.81
row_6		fig	$13.26
row_7	777,000.00	grapefruit
row_8	8,880,000.00	honeydew	$0.44
This is only a subset of the dataset.

With the table_background_color option, we can modify the table’s background color. Here, we want that to be "lightcyan".

gt_tbl.tab_options(table_background_color="lightcyan")

	num	char	currency
Data listing from exibble
`exibble` is a Great Tables dataset.
grp_a
row_1	0.11	apricot	$49.95
row_2	2.22	banana	$17.95
row_3	33.33	coconut	$1.39
row_4	444.40	durian	$65,100.00
grp_b
row_5	5,550.00		$1,325.81
row_6		fig	$13.26
row_7	777,000.00	grapefruit
row_8	8,880,000.00	honeydew	$0.44
This is only a subset of the dataset.

The data rows of a table typically take up the most physical space but we have some control over the extent of that. With the data_row_padding option, it’s possible to modify the top and bottom padding of data rows. We’ll do just that in the following example, reducing the padding to a value of "3px".

gt_tbl.tab_options(data_row_padding="3px")

	num	char	currency
Data listing from exibble
`exibble` is a Great Tables dataset.
grp_a
row_1	0.11	apricot	$49.95
row_2	2.22	banana	$17.95
row_3	33.33	coconut	$1.39
row_4	444.40	durian	$65,100.00
grp_b
row_5	5,550.00		$1,325.81
row_6		fig	$13.26
row_7	777,000.00	grapefruit
row_8	8,880,000.00	honeydew	$0.44
This is only a subset of the dataset.

The size of the title and the subtitle text in the header of the table can be altered with the heading_title_font_size and heading_subtitle_font_size options. Here, we’ll use the "small" and "x-small" keyword values.

gt_tbl.tab_options(heading_title_font_size="small", heading_subtitle_font_size="x-small")

	num	char	currency
Data listing from exibble
`exibble` is a Great Tables dataset.
grp_a
row_1	0.11	apricot	$49.95
row_2	2.22	banana	$17.95
row_3	33.33	coconut	$1.39
row_4	444.40	durian	$65,100.00
grp_b
row_5	5,550.00		$1,325.81
row_6		fig	$13.26
row_7	777,000.00	grapefruit
row_8	8,880,000.00	honeydew	$0.44
This is only a subset of the dataset.