## GT.fmt_icon()
Use icons within a table's body cells.
Usage
``` python
GT.fmt_icon(
columns=None,
rows=None,
height=None,
sep=" ",
stroke_color=None,
stroke_width=None,
stroke_alpha=None,
fill_color=None,
fill_alpha=None,
margin_left=None,
margin_right=None
)
```
We can draw from a library of thousands of icons and selectively insert them into a table. The [fmt_icon()](GT.fmt_icon.md#great_tables.GT.fmt_icon) method makes this possible by mapping input cell labels to an icon name. We are exclusively using Font Awesome icons here so the reference is the short icon name. Multiple icons can be included per cell by separating icon names with commas (e.g., `"hard-drive,clock"`). The `sep=` argument allows for a common separator to be applied between icons.
## 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 | None = None`
The absolute height of the icon in the table cell. By default, this is set to "1em".
`sep: str = ``" "`
In the output of icons within a body cell, `sep=` provides the separator between each icon.
`stroke_color: str | None = None`
The icon stroke is essentially the outline of the icon. The color of the stroke can be modified by applying a single color here. If not provided then the default value of `"currentColor"` is applied so that the stroke color matches that of the parent HTML element's color attribute.
`stroke_width: str | int | None = None`
The `stroke_width=` option allows for setting the color of the icon outline stroke. By default, the stroke width is very small at "1px" so a size adjustment here can sometimes be useful. If an integer value is provided then it is assumed to be in pixels.
`stroke_alpha: float | None = None`
The level of transparency for the icon stroke can be controlled with a decimal value between `0` and `1`.
`fill_color: str | dict[str, str] | None = None`
The fill color of the icon can be set with `fill_color=`; providing a single color here will change the color of the fill but not of the icon's 'stroke' or outline (use `stroke_color=` to modify that). A dictionary comprising the icon names with corresponding fill colors can alternatively be used here (e.g., `{"circle-check" = "green", "circle-xmark" = "red"}`. If nothing is provided then the default value of `"currentColor"` is applied so that the fill matches the color of the parent HTML element's color attribute.
`fill_alpha: float | None = None`
The level of transparency for the icon fill can be controlled with a decimal value between `0` and `1`.
`margin_left: str | None = None`
The length value for the margin that's to the left of the icon. By default, `"auto"` is used for this but if space is needed on the left-hand side then a length of `"0.2em"` is recommended as a starting point.
`margin_right: str | None = None`
The length value for the margin right of the icon. By default, `"auto"` is used but if space is needed on the right-hand side then a length of `"0.2em"` is recommended as a starting point.
## 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
For this first example of generating icons with [fmt_icon()](GT.fmt_icon.md#great_tables.GT.fmt_icon), let's make a simple DataFrame that has two columns of Font Awesome icon names. We separate multiple icons per cell with commas. By default, the icons are 1 em in height; we're going to make the icons slightly larger here (so we can see the fine details of them) by setting height = "4em".
``` python
import pandas as pd
from great_tables import GT
animals_foods_df = pd.DataFrame(
{
"animals": ["hippo", "fish,spider", "mosquito,locust,frog", "dog,cat", "kiwi-bird"],
"foods": ["bowl-rice", "egg,pizza-slice", "burger,lemon,cheese", "carrot,hotdog", "bacon"],
}
)
(
GT(animals_foods_df)
.fmt_icon(
columns=["animals", "foods"],
height="4em"
)
.cols_align(
align="center",
columns=["animals", "foods"]
)
)
```
| animals | foods |
|----|----|
IDE3Nkg3MmMxMy4zIDAgMjQgMTAuNyAyNCAyNHMtMTAuNyAyNC0yNCAyNEg1NmMtMTMuMyAwLTI0LTEwLjctMjQtMjRzMTAuNy0yNCAyNC0yNHpNMCAyODMuNEMwIDI2OC4zIDEyLjMgMjU2IDI3LjQgMjU2SDQ4NC42YzE1LjEgMCAyNy40IDEyLjMgMjcuNCAyNy40YzAgNzAuNS00NC40IDEzMC43LTEwNi43IDE1NC4xTDQwMy41IDQ1MmMtMiAxNi0xNS42IDI4LTMxLjggMjhIMTQwLjJjLTE2LjEgMC0yOS44LTEyLTMxLjgtMjhsLTEuOC0xNC40QzQ0LjQgNDE0LjEgMCAzNTMuOSAwIDI4My40ek0yMjQgMjAwYzAtMTMuMyAxMC43LTI0IDI0LTI0aDE2YzEzLjMgMCAyNCAxMC43IDI0IDI0cy0xMC43IDI0LTI0IDI0SDI0OGMtMTMuMyAwLTI0LTEwLjctMjQtMjR6bS05NiAwYzAtMTMuMyAxMC43LTI0IDI0LTI0aDE2YzEzLjMgMCAyNCAxMC43IDI0IDI0cy0xMC43IDI0LTI0IDI0SDE1MmMtMTMuMyAwLTI0LTEwLjctMjQtMjR6bS0yNC05NmgxNmMxMy4zIDAgMjQgMTAuNyAyNCAyNHMtMTAuNyAyNC0yNCAyNEgxMDRjLTEzLjMgMC0yNC0xMC43LTI0LTI0czEwLjctMjQgMjQtMjR6bTIxNiA5NmMwLTEzLjMgMTAuNy0yNCAyNC0yNGgxNmMxMy4zIDAgMjQgMTAuNyAyNCAyNHMtMTAuNyAyNC0yNCAyNEgzNDRjLTEzLjMgMC0yNC0xMC43LTI0LTI0em0tMjQtOTZoMTZjMTMuMyAwIDI0IDEwLjcgMjQgMjRzLTEwLjcgMjQtMjQgMjRIMjk2Yy0xMy4zIDAtMjQtMTAuNy0yNC0yNHMxMC43LTI0IDI0LTI0em0xMjAgOTZjMC0xMy4zIDEwLjctMjQgMjQtMjRoMTZjMTMuMyAwIDI0IDEwLjcgMjQgMjRzLTEwLjcgMjQtMjQgMjRINDQwYy0xMy4zIDAtMjQtMTAuNy0yNC0yNHptLTI0LTk2aDE2YzEzLjMgMCAyNCAxMC43IDI0IDI0cy0xMC43IDI0LTI0IDI0SDM5MmMtMTMuMyAwLTI0LTEwLjctMjQtMjRzMTAuNy0yNCAyNC0yNHpNMjk2IDMyaDE2YzEzLjMgMCAyNCAxMC43IDI0IDI0cy0xMC43IDI0LTI0IDI0SDI5NmMtMTMuMyAwLTI0LTEwLjctMjQtMjRzMTAuNy0yNCAyNC0yNHoiIC8+PC9zdmc+" class="fa" /> |
| 
| 
|
| 
| 
|
| 
| 
|
| 
| 
|
Let's take a few rows from the towny dataset and make it so the `csd_type` column contains *Font Awesome* icon names (we want only the `"city"` and `"house-chimney"` icons here). After using [fmt_icon()](GT.fmt_icon.md#great_tables.GT.fmt_icon) to format the `csd_type` column, we get icons that are representative of the two categories of municipality for this subset of data.
``` python
import polars as pl
from great_tables.data import towny
towny_mini = (
pl.from_pandas(towny.loc[[323, 14, 26, 235]])
.select(["name", "csd_type", "population_2021"])
.with_columns(
csd_type = pl.when(pl.col("csd_type") == "town")
.then(pl.lit("house-chimney"))
.otherwise(pl.lit("city"))
)
)
(
GT(towny_mini)
.fmt_integer(columns="population_2021")
.fmt_icon(columns="csd_type")
.cols_label(
csd_type="",
name="City/Town",
population_2021="Population"
)
)
```
| City/Town | | Population |
|----|----|----|
| Sarnia | 
| 72,047 |
| Arnprior | 
| 9,629 |
| Barrie | | 147,829 |
| Milton | | 132,979 |
A fairly common thing to do with icons in tables is to indicate whether a quantity is either higher or lower than another. Up and down arrow symbols can serve as good visual indicators for this purpose. We can make use of the `"up-arrow"` and `"down-arrow"` icons here. As those strings are available in the `dir` column of the table derived from the [sp500](data.sp500.md#great_tables.data.sp500) dataset, [fmt_icon()](GT.fmt_icon.md#great_tables.GT.fmt_icon) can be used. We set the `fill_color` argument with a dictionary that indicates which color should be used for each icon.
``` python
from great_tables.data import sp500
sp500_mini = (
pl.from_pandas(sp500)
.head(10)
.select(["date", "open", "close"])
.sort("date", descending=False)
.with_columns(
dir = pl.when(pl.col("close") >= pl.col("open")).then(
pl.lit("arrow-up")).otherwise(pl.lit("arrow-down"))
)
)
(
GT(sp500_mini, rowname_col="date")
.fmt_icon(
columns="dir",
fill_color={"arrow-up": "green", "arrow-down": "red"}
)
.cols_label(
open="Opening Value",
close="Closing Value",
dir=""
)
.opt_stylize(style=1, color="gray")
)
```
| | Opening Value | Closing Value | |
|----|----|----|----|
| 2015-12-17 | 2073.76 | 2041.89 | 
|
| 2015-12-18 | 2040.8101 | 2005.55 | |
| 2015-12-21 | 2010.27 | 2021.15 | 
|
| 2015-12-22 | 2023.15 | 2038.97 | |
| 2015-12-23 | 2042.2 | 2064.29 | |
| 2015-12-24 | 2063.52 | 2060.99 | |
| 2015-12-28 | 2057.77 | 2056.5 | |
| 2015-12-29 | 2060.54 | 2078.3601 | |
| 2015-12-30 | 2077.3401 | 2063.3601 | |
| 2015-12-31 | 2060.5901 | 2043.9399 | |