Pie & Donut Card

Card type: pieChart

The pie/donut card displays a pie or donut chart from tabular data. You can control the inner and outer radius, colors, and labels.

In addition to the common parameters the pieChart card has the following configuration options:

Name	Type	Required	Default	Description
`value`	list of dict	Yes	—	The data to be plotted. Each dict is a slice.
`fillCard`	bool	No	`false`	When set to `True`, the chart will fill the entire card space including the header area. When `False` (default), the chart will be positioned below the header.
`label_override`	dict	No	—	Optional: pretty labels for slices.
`chart_options`	dict	Yes	—	Chart configuration options. See table below.

Chart Options

Name	Type	Required	Default	Description
`nameKey`	str	Yes	—	The property in each dict to use for the slice name. See examples below.
`dataKey`	str	Yes	—	The property in each dict to use for the slice value.
`fillKey`	str	No	—	The property in each dict to use for the slice color.
`showLabels`	bool	No	`true`	Whether to show labels on the slices.
`labelType`	”name” or “data”	No	`"name"`	Show the name or value as the label.
`labelLine`	bool	No	`true`	Whether to show lines connecting labels to slices.
`labelScaleDistance`	number	No	(auto)	How far labels are placed from the center (if not, set, this scales with the card size).
`innerRadius`	str or int	No	`"0%"`	Inner radius (e.g. 0 for pie, “50%” for donut). Set an integer value to make the chart a fixed size. See examples below.
`outerRadius`	str or int	No	`"100%"`	Outer radius (e.g. “90%”, 80). Set an integer value to make the chart a fixed size. See examples below.
`paddingAngle`	number	No	`0`	Angle between segments in degrees.
`defaultColors`	”monochrome” or “multicolor”	No	`"monochrome"`	Fallback color scheme if no color is provided in the data.
`fontSize`	str	No	(auto)	Font size for labels/tooltips. (if not set, this scales with the card size).
`showLegend`	bool	No	`true`	Whether to show the legend below the chart. Mutually exclusive with `showCentralText`.
`showCentralText`	bool	No	`false`	Whether to show text in the center of the chart. By default, this is the total sum of all values. Override it by setting `centralTextValue`. Mutually exclusive with `showLegend`.
`centralTextValue`	str	No	—	Custom text to display in the center.
`centralTextLabel`	str	No	—	Label to show below the main central text.

Legend and Central Text

Mutual Exclusivity: showLegend and showCentralText cannot be used simultaneously. If both are set to true, showCentralText will take precedence and showLegend will be disabled.

Inner and outer radius

Absolute values (fixed size):

innerRadius: 0, outerRadius: 80 → Pie chart with 80px radius
innerRadius: 40, outerRadius: 80 → Donut chart with 40px inner and 80px outer radius

Percentage values (scales with card size):

innerRadius: “0%”, outerRadius: “80%” → Pie chart at 80% of card size
innerRadius: “50%”, outerRadius: “80%” → Donut chart with 50% inner and 80% outer radius

Examples

Donut Chart


import polars as pl
 
# Create some data
df = pl.DataFrame({
    "fruit": ["apples", "oranges", "bananas", "grapes", "pears"],
    "count": [30, 25, 20, 15, 10],
})
 
# Convert to the format expected by the pie chart
data = df.to_dicts()
 
# Override labels
label_override = {
    "apples": {"label": "Apples"},
    "oranges": {"label": "Oranges"},
    "bananas": {"label": "Bananas"},
    "grapes": {"label": "Grapes"},
    "pears": {"label": "Pears"},
}
 
datacards.publish.card(
    type='pieChart',
    value=data,
    label="Fruit",
    chart_options={
        "nameKey": "fruit",
        "dataKey": "count",
        "innerRadius": "50%",  # Donut
        "outerRadius": "90%",
        "labelType": "name",
        "showLabels": True,
    },
    label_override=label_override,
    logic_view_size=(4,2),
)

Pie Chart (no inner radius)

Using data option for label type.


import polars as pl
 
# Create some data
df = pl.DataFrame({
    "browser": ["chrome", "safari", "firefox", "edge", "other"],
    "users": [275, 200, 187, 173, 90],
})
 
# Convert to the format expected by the pie chart
data = df.to_dicts()
 
# Override labels
label_override = {
    "chrome": {"label": "Chrome"},
    "safari": {"label": "Safari"},
    "firefox": {"label": "Firefox"},
    "edge": {"label": "Edge"},
    "other": {"label": "Other"},
}
 
datacards.publish.card(
    type='pieChart',
    value=data,
    label="Browser Share",
    chart_options={
        "nameKey": "browser",
        "dataKey": "users",
        "innerRadius": 0,  # Pie
        "outerRadius": "100%",
        "labelType": "name",
        "showLabels": True,
    },
    label_override=label_override,
    logic_view_size=(4,2),
)

Pie Chart with Custom Colors


import polars as pl
 
# Create some data
df = pl.DataFrame({
    "category": ["A", "B", "C", "D"],
    "value": [40, 30, 20, 10],
    "color": ["#ff0000", "#00ff00", "#0000ff", None],  # None will use fallback
})
 
# Convert to the format expected by the pie chart
data = df.to_dicts()
 
# Override labels
label_override = {
    "A": {"label": "Category Alpha"},
    "B": {"label": "Category Beta"},
    "C": {"label": "Category Gamma"},
    "D": {"label": "Category Delta"},
}
 
datacards.publish.card(
    type='pieChart',
    value=data,
    label="Category",
    chart_options={
        "nameKey": "category",
        "dataKey": "value",
        "fillKey": "color",
        "defaultColors": "multicolor",
        "innerRadius": 0,
        "outerRadius": "90%",
        "labelType": "name",
        "showLabels": True,
    },
    label_override=label_override,
    logic_view_size=(4,2),
)

Pie Chart with Legend (No Labels)

When you have many slices or want a cleaner look, you can disable labels and rely on the legend instead.


import polars as pl
 
# Create some data
df = pl.DataFrame({
    "category": ["Electronics", "Clothing", "Books", "Home", "Sports", "Beauty"],
    "sales": [1200, 800, 600, 450, 300, 250],
})
 
# Convert to the format expected by the pie chart
data = df.to_dicts()
 
# Override labels for the legend
label_override = {
    "Electronics": {"label": "Electronics"},
    "Clothing": {"label": "Clothing"},
    "Books": {"label": "Books"},
    "Home": {"label": "Home & Garden"},
    "Sports": {"label": "Sports & Outdoors"},
    "Beauty": {"label": "Beauty & Health"},
}
 
datacards.publish.card(
    type='pieChart',
    value=data,
    label="Sales by Category",
    chart_options={
        "nameKey": "category",
        "dataKey": "sales",
        "showLabels": False,  # Disable slice labels
        "showLegend": True,   # Show legend instead
        "defaultColors": "monochrome",
        "innerRadius": "0%",
        "outerRadius": "80%",
    },
    label_override=label_override,
    logic_view_size=(8,6),
)

Donut Chart with Central Text

You can add text in the center of the chart to show totals or custom information.


import polars as pl
 
# Create some data
df = pl.DataFrame({
    "category": ["Revenue", "Expenses", "Profit"],
    "amount": [50000, 35000, 15000],
})
 
# Convert to the format expected by the pie chart
data = df.to_dicts()
 
# Override labels
label_override = {
    "Revenue": {"label": "Revenue"},
    "Expenses": {"label": "Expenses"},
    "Profit": {"label": "Net Profit"},
}
 
datacards.publish.card(
    type='pieChart',
    value=data,
    label="Financial Overview",
    chart_options={
        "nameKey": "category",
        "dataKey": "amount",
        "innerRadius": "50%",  # Donut
        "outerRadius": "90%",
        "showLabels": False,   # Hide slice labels
        "showLegend": True,    # Show legend instead
        "showCentralText": True,  # Enable central text
        "centralTextValue": "$100K",  # Custom text in center
        "centralTextLabel": "Total",  # Label below the text
        "defaultColors": "multicolor",
    },
    label_override=label_override,
    logic_view_size=(6,4),
)

Donut Chart with Custom central text

If you don’t provide centralTextValue, the chart will automatically show the sum of all values.


import polars as pl
 
# Create some data
df = pl.DataFrame({
    "category": ["Revenue", "Expenses", "Profit"],
    "amount": [50000, 35000, 15000],
})
 
# Convert to the format expected by the pie chart
data = df.to_dicts()
 
# Override labels
label_override = {
    "Revenue": {"label": "Revenue"},
    "Expenses": {"label": "Expenses"},
    "Profit": {"label": "Net Profit"},
}
 
datacards.publish.card(
    type='pieChart',
    value=data,
    label="Financial Overview",
    chart_options={
        "nameKey": "category",
        "dataKey": "amount",
        "innerRadius": "60%",  # Donut
        "outerRadius": "90%",
        "showCentralText": True,  # Enable central text
        "showLabels": False,
        "centralTextValue": "10.000€",  # Custom text in center
        "centralTextLabel": "Total",  # Label below the text
        "defaultColors": "multicolor",
    },
    label_override=label_override,
    logic_view_size=(6,4),
)

Donut chart with custom central text example