gt-extras
  • Intro
  • Examples
  • API Reference
  1. Icons and Images
  2. gt_fmt_img_circle
  • API Reference
  • Plotting
    • gt_plt_bar
    • gt_plt_bar_pct
    • gt_plt_bar_stack
    • gt_plt_bullet
    • gt_plt_conf_int
    • gt_plt_donut
    • gt_plt_dot
    • gt_plt_dumbbell
    • gt_plt_summary
    • gt_plt_winloss
  • Colors
    • gt_color_box
    • gt_data_color_by_group
    • gt_highlight_cols
    • gt_highlight_rows
    • gt_hulk_col_numeric
  • Themes
    • gt_theme_538
    • gt_theme_dark
    • gt_theme_dot_matrix
    • gt_theme_espn
    • gt_theme_excel
    • gt_theme_guardian
    • gt_theme_nytimes
    • gt_theme_pff
  • Icons and Images
    • add_text_img
    • fa_icon_repeat
    • gt_fa_rank_change
    • gt_fa_rating
    • gt_fmt_img_circle
    • img_header
  • Utilities
    • fmt_pct_extra
    • gt_add_divider
    • gt_duplicate_column
    • gt_merge_stack
    • gt_two_column_layout
    • with_hyperlink
    • with_tooltip

On this page

  • Parameters
  • Returns
  • Examples
  1. Icons and Images
  2. gt_fmt_img_circle

gt_fmt_img_circle

gt_fmt_img_circle(
    gt,
    columns=None,
    rows=None,
    height=None,
    width=None,
    border_radius='50%',
    border_width=None,
    border_color=None,
    border_style=None,
    sep=' ',
    path=None,
    file_pattern='{}',
    encode=True,
)

Format image paths to generate circular images within table cells. gt_fmt_img_circle() is a utility function similar to GT.fmt_image(), but it also accepts additional parameters for customizing the image border: border_radius=, border_width=, border_color=, and border_style=.

When calling gt_fmt_img_circle(), gt-extras automatically sets border_radius="50%" to create a full circle. However, we can’t assume whether you want the border to be visible. Therefore, you should supply at least one of the following: border_width=, border_color=, or border_style=. Based on your input, sensible defaults will be applied for any unset border properties.

Parameters

columns : SelectExpr = None

The columns to target. Can either be a single column name or a series of column names provided in a list.

rows : int | list[int] | None = None

In conjunction with columns=, we can specify which of their rows should undergo formatting. The default is all rows, resulting in all rows in targeted columns being formatted. Alternatively, we can supply a list of row indices.

height : str | int | None = None

The height of the rendered images.

width : str | None = None

The width of the rendered images.

border_radius : str | None = '50%'

The radius of the image border. Accepts values in pixels (px) or percentages (%). Defaults to 50% to create a circular image.

border_width : str | int | None = None

The width of the image border.

border_color : str | None = None

The color of the image border.

border_style : str | None = None

The style of the image border (e.g., "solid", "dashed", "dotted").

sep : str = ' '

In the output of images within a body cell, sep= provides the separator between each image.

path : str | Path | None = None

An optional path to local image files or an HTTP/HTTPS URL. This is combined with the filenames to form the complete image paths.

file_pattern : str = '{}'

The pattern to use for mapping input values in the body cells to the names of the graphics files. The string supplied should use "{}" in the pattern to map filename fragments to input strings.

encode : bool = True

The option to always use Base64 encoding for image paths that are determined to be local. By default, this is True.

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

import polars as pl
from great_tables import GT
import gt_extras as gte

rich_avatar = "https://avatars.githubusercontent.com/u/5612024?v=4"
michael_avatar = "https://avatars.githubusercontent.com/u/2574498?v=4"
jules_avatar = "https://avatars.githubusercontent.com/u/54960783?v=4"


df = pl.DataFrame({
    "@machow": [michael_avatar],
    "@rich-iannone": [rich_avatar],
    "@juleswg23": [jules_avatar]
})

(
    GT(df)
    .cols_align("center")
    .opt_stylize(color="green", style=6)
    .pipe(gte.gt_fmt_img_circle, height=80)
)
@machow @rich-iannone @juleswg23
gt_fa_rating
img_header