Bar Chart Card

Card type: barChart

The bar chart card displays a bar chart from tabular data. You can control colors, bar sizes, and labels.

In addition to the common parameters the barChart 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 bar or group of bars.
`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 (categories).
`yKeys`	list of str	Yes	—	The properties in each dict to use for the y-axis values (bar heights).
`fillKeys`	list of str	No	—	The properties in each dict to use for the bar colors.
`layout`	”horizontal” or “vertical”	No	`"vertical"`	Chart layout - horizontal or vertical bars.
`fillOpacity`	number	No	`0.8`	Opacity of the filled bars (0-1).
`strokeWidth`	number	No	`1`	Width of the stroke line around bars.
`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	(auto)	Chart margins: `{top, right, bottom, left}`.
`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	`{}`	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.

Examples

Simple Bar Chart


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 bar chart
data = df.to_dicts()
 
# Override labels
label_override = {
    "visitors": {"label": "Visitors"},
}
 
datacards.publish.card(
    type='barChart',
    value=data,
    label="Monthly Visitors",
    chart_options={
        "xKey": "month",
        "yKeys": ["visitors"],
        "defaultColors": "monochrome",
    },
    label_override=label_override,
    logic_view_size=(4,2),
)

Multiple Series Bar Chart


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 bar chart
data = df.to_dicts()
 
# Override labels
label_override = {
    "desktop": {"label": "Desktop"},
    "mobile": {"label": "Mobile"},
}
 
datacards.publish.card(
    type='barChart',
    value=data,
    label="Monthly Visitors by Device",
    chart_options={
        "xKey": "month",
        "yKeys": ["desktop", "mobile"],
        "defaultColors": "multicolor",
    },
    label_override=label_override,
    logic_view_size=(6,4),
)

Bar 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", "#ffff00"],
})
 
# Convert to the format expected by the bar chart
data = df.to_dicts()
 
# Override labels
label_override = {
    "value": {"label": "Value"},
    "A": {"label": "Category Alpha"},
    "B": {"label": "Category Beta"},
    "C": {"label": "Category Gamma"},
    "D": {"label": "Category Delta"},
}
 
datacards.publish.card(
    type='barChart',
    value=data,
    label="Category Values",
    chart_options={
        "xKey": "category",
        "yKeys": ["value"],
        "fillKeys": ["color"],
        "defaultColors": "multicolor",
        "fillOpacity": 0.9,
        "strokeWidth": 2,
    },
    label_override=label_override,
    logic_view_size=(4,2),
)

Bar Chart with Negative Values

This example shows a bar chart with negative values, which is useful for displaying profit/loss data or other metrics that can go below zero.


import polars as pl
 
# Create some data with negative values
df = pl.DataFrame({
    "month": ["Jan", "Feb", "Mar", "Apr", "May", "Jun"],
    "profit": [1200, -800, 450, -1200, 1800, -300],
})
 
# Convert to the format expected by the bar chart
data = df.to_dicts()
 
# Override labels
label_override = {
    "profit": {"label": "Profit/Loss"},
}
 
datacards.publish.card(
    type='barChart',
    value=data,
    label="Monthly Profit/Loss",
    chart_options={
        "xKey": "month",
        "yKeys": ["profit"],
    },
    label_override=label_override,
    logic_view_size=(6,3),
)

Horizontal Bar Chart


import polars as pl
 
# Create some data
df = pl.DataFrame({
    "month": ["January", "February", "March", "April", "May", "June"],
    "desktop": [186, 305, 237, 73, 209, 214],
})
 
# Convert to the format expected by the bar chart
data = df.to_dicts()
 
# Override labels
label_override = {
    "desktop": {"label": "Desktop"},
}
 
datacards.publish.card(
    type='barChart',
    value=data,
    label="Monthly Desktop Visitors",
    chart_options={
        "xKey": "month",
        "yKeys": ["desktop"],
        "layout": "horizontal",
        "margin": {
        "top": 15,
        "right": 20,
        "bottom": 10,
        "left": 15,
      },
    },
    label_override=label_override,
    logic_view_size=(6,4)
)