Area Chart Card

Card type: areaChart

The area chart card displays an area chart from tabular data. You can control the area type, colors, opacity, and various display options.

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

Name	Type	Required	Default	Description
`value`	list of dict	Yes	—	The data to be plotted. Each dict represents a data point.
`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 data series.
`chart_options`	dict	Yes	—	Chart configuration options. See table below.

Chart Options

Name	Type	Required	Default	Description
`xKey`	str	Yes	—	The property in each dict to use for the x-axis values.
`yKeys`	list of str	Yes	—	The properties in each dict to use for the y-axis values (can be multiple series).
`fillKeys`	list of str	No	—	The properties in each dict to use for the fill colors of each series.
`areaType`	”natural”, “linear”, “step”	No	`"natural"`	The type of area curve to use.
`fillOpacity`	number	No	`0.4`	Opacity of the filled area (0-1).
`strokeWidth`	number	No	`2`	Width of the stroke line.
`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.
`showGrid`	bool	No	`true`	Whether to show the grid lines.
`showYAxis`	bool	No	`true`	Whether to show the y-axis.
`margin`	dict	No	`{top: 15, right: 15, bottom: 15, left: -10}`	Chart margins.
`xAxisConfig`	dict	No	`{tickLine: false, axisLine: false, tickMargin: 8, maxChars: 3}`	X-axis configuration (tickLine, axisLine, tickMargin, maxChars).
`yAxisConfig`	dict	No	`{tickLine: false, axisLine: false, tickMargin: 8, maxChars: 10}`	Y-axis configuration (tickLine, axisLine, tickMargin, maxChars).
`gridConfig`	dict	No	`{vertical: true, horizontal: true}`	Grid configuration (vertical, horizontal).

Axis labels

X-axis labels are automatically truncated to 3 characters and Y-axis labels to 10 characters to prevent overcrowding. You can override this using maxChars in xAxisConfig or yAxisConfig.

Area Types

"natural": Smooth curved area (default)
"linear": Straight line connections between points
"step": Step-like area with horizontal and vertical segments

Examples

Simple Area Chart

This example shows a basic area chart with a single data series.


import polars as pl
 
# Create some data
df = pl.DataFrame({
    "month": ["January", "February", "March", "April", "May", "June"],
    "visitors": [186, 305, 237, 73, 209, 214],
})
 
# Convert to the format expected by the area chart
data = df.to_dicts()
 
# Override labels
label_override = {
    "visitors": {"label": "Visitors"},
}
 
datacards.publish.card(
    type='areaChart',
    value=data,
    label="Website Visitors",
    chart_options={
        "xKey": "month",
        "yKeys": ["visitors"],
    },
    label_override=label_override,
    logic_view_size=(4,2),
)

Multi-Series Area Chart

This example demonstrates multiple data series with different colors. Each series gets its own area with automatic color assignment.


import polars as pl
 
# Create some data
df = pl.DataFrame({
    "month": ["January", "February", "March", "April", "May", "June"],
    "desktop": [186, 305, 237, 73, 209, 214],
    "mobile": [120, 200, 180, 90, 150, 160],
})
 
# Convert to the format expected by the area chart
data = df.to_dicts()
 
# Override labels
label_override = {
    "desktop": {"label": "Desktop"},
    "mobile": {"label": "Mobile"},
}
 
datacards.publish.card(
    type='areaChart',
    value=data,
    label="Traffic by Device",
    chart_options={
        "xKey": "month",
        "yKeys": ["desktop", "mobile"],
        "defaultColors": "multicolor",
    },
    label_override=label_override,
    logic_view_size=(4,2),
)

Step Area Chart

This example shows a step area chart, which is useful for data that changes at discrete intervals.


import polars as pl
 
# Create some data
df = pl.DataFrame({
    "time": ["00:00", "04:00", "08:00", "12:00", "16:00", "20:00"],
    "temperature": [15, 12, 18, 25, 28, 22],
})
 
# Convert to the format expected by the area chart
data = df.to_dicts()
 
# Override labels
label_override = {
    "temperature": {"label": "Temperature (°C)"},
}
 
datacards.publish.card(
    type='areaChart',
    value=data,
    label="Daily Temperature",
    chart_options={
        "xKey": "time",
        "yKeys": ["temperature"],
        "areaType": "step",
        "xAxisConfig": {"maxChars": 5},
        "margin": {"top": 15, "right": 25, "bottom": 10, "left": -10}
    },
    label_override=label_override,
    logic_view_size=(4,2),
)

Area Chart with Custom Colors

This example demonstrates how to specify custom colors for each data series using the fillKeys option.


import polars as pl
 
# Create some data
df = pl.DataFrame({
    "quarter": ["Q1", "Q2", "Q3", "Q4"],
    "revenue": [1000, 1200, 1100, 1400],
    "costs": [800, 900, 850, 1000],
    "revenue_color": ["#10b981", "#10b981", "#10b981", "#10b981"],
    "costs_color": ["#ef4444", "#ef4444", "#ef4444", "#ef4444"],
})
 
# Convert to the format expected by the area chart
data = df.to_dicts()
 
# Override labels
label_override = {
    "revenue": {"label": "Revenue"},
    "costs": {"label": "Costs"},
}
 
datacards.publish.card(
    type='areaChart',
    value=data,
    label="Financial Overview",
    chart_options={
        "xKey": "quarter",
        "yKeys": ["revenue", "costs"],
        "fillKeys": ["revenue_color", "costs_color"],
        "areaType": "linear",
        "fillOpacity": 0.5,
    },
    label_override=label_override,
    logic_view_size=(4,2),
)