Component | Bar Chart

info

Introduced in SDK v0.25.0

Render a bar chart. Bar charts offer:

• Aesthetic defaults for a clean, professional look.
• Flexible customization options for orientation, scale, grouping, etc.
• Built-in data transformation utilities for easy formatting.
• Canvas rendering for efficient scaling to thousands of bars.

Node.js

const salesData = [
  { month: "Jan", California: 95, Texas: 120, "New York": 310 },
  { month: "Feb", California: 105, Texas: 135, "New York": 290 },
  /* ... */
  { month: "Dec", California: 250, Texas: 300, "New York": 520 },
];

page.add(() =>
  ui.barChart("sales-chart", salesData, {
    group: "month",
    series: ["California", "Texas", "New York"],
    groupMode: "grouped",
    label: "Monthly Sales by Region",
  })
);

Python

sales_data = [
  { "month": "Jan", "California": 95, "Texas": 120, "New York": 310 },
  { "month": "Feb", "California": 105, "Texas": 135, "New York": 290 },
  # ...
  { "month": "Dec", "California": 250, "Texas": 300, "New York": 520 },
]

page.add(() =>
  ui.bar_chart(
    "sales-chart",
    sales_data,
    group="month",
    series=["California", "Texas", "New York"],
    group_mode="grouped",
    label="Monthly Sales by Region"
  )
)

Group rows

You'll likely need to re-format your data in order to chart it. Compose provides simple utilities to help you do this.

First, you'll need to group your data. For example, for a monthly chart, you'd group by month. Specify the group parameter to specify how rows in your data should be grouped:

• A string key from your data
• A function that receives each row and its index, returning a group label
• If not provided, defaults to using the "group" key from your data

Node.js

const salesData = [
  { date: "2023-01-15", product: "Laptop", revenue: 2500 },
  { date: "2023-02-22", product: "Monitor", revenue: 800 },
  { date: "2023-02-05", product: "Laptop", revenue: 2200 },
  { date: "2023-02-18", product: "Monitor", revenue: 900 },
  { date: "2023-03-10", product: "Laptop", revenue: 2800 },
  { date: "2023-03-25", product: "Monitor", revenue: 750 },
];

function getMonth(row) {
  return new Date(row.date).toLocaleString('default', { month: 'long' });
}

page.add(() =>
  ui.barChart("monthly-chart", salesData, {
    group: (row) => getMonth(row), // Group the data by month
    series: ["revenue"],
    label: "Monthly Revenue"
  })
);

Python

from datetime import datetime

sales_data = [
  { "date": "2023-01-15", "product": "Laptop", "revenue": 2500 },
  { "date": "2023-02-22", "product": "Monitor", "revenue": 800 },
  { "date": "2023-02-05", "product": "Laptop", "revenue": 2200 },
  { "date": "2023-02-18", "product": "Monitor", "revenue": 900 },
  { "date": "2023-03-10", "product": "Laptop", "revenue": 2800 },
  { "date": "2023-03-25", "product": "Monitor", "revenue": 750 },
]

def get_month(row):
  return datetime.strptime(row["date"], "%Y-%m-%d").strftime("%B")

page.add(lambda:
  ui.bar_chart(
    "monthly-chart",
    sales_data,
    group=get_month, # Group the data by month
    series=["revenue"],
    label="Monthly Revenue"
  )
)

Aggregate rows

Compose will aggregate rows with the same group value according to the aggregate parameter.

By default, the rows are aggregated by sum. You can also aggregate by count, average, min, or max.

Node.js

const salesData = [
  { date: "2023-01-15", product: "Laptop", revenue: 2500 },
  /* ... */
  { date: "2023-03-25", product: "Monitor", revenue: 750 },
];

function getMonth(row) {
  return new Date(row.date).toLocaleString('default', { month: 'long' });
}

page.add(() =>
  ui.barChart("monthly-chart", salesData, {
    group: (row) => getMonth(row),
    series: ["product"],
    aggregate: "count", // Aggregate by count
    label: "Products Sold by Month"
  })
);

Python

from datetime import datetime

sales_data = [
  { "date": "2023-01-15", "product": "Laptop", "revenue": 2500 },
  # ...
  { "date": "2023-03-25", "product": "Monitor", "revenue": 750 },
]

def get_month(row):
  return datetime.strptime(row["date"], "%Y-%m-%d").strftime("%B")

page.add(lambda:
  ui.bar_chart(
    "monthly-chart",
    sales_data,
    group=get_month,
    series=["product"],
    aggregate="count", # Aggregate by count
    label="Products Sold by Month"
  )
)

Segment within groups

Within each group, you can further segment your data by using the series parameter, which controls the bars that render for each group.

For example, you may want to break down your monthly sales by region.

Basic usage

You can pass a list of keys from your data to the series parameter, which will map to the bars that render for each group.

Node.js

const salesData = [
  { month: "Jan", California: 95, Texas: 120, "New York": 310 },
  { month: "Feb", California: 105, Texas: 135, "New York": 290 },
  /* ... */
  { month: "Dec", California: 250, Texas: 300, "New York": 520 },
];

page.add(() =>
  ui.barChart("sales-chart", salesData, {
    group: "month",
    series: ["California", "Texas"]
    groupMode: "grouped",
    label: "Monthly Sales by Region",
  })
);

Python

sales_data = [
  { "month": "Jan", "California": 95, "Texas": 120, "New York": 310 },
  { "month": "Feb", "California": 105, "Texas": 135, "New York": 290 },
  # ...
  { "month": "Dec", "California": 250, "Texas": 300, "New York": 520 },
]

page.add(() =>
  ui.bar_chart(
    "sales-chart",
    sales_data,
    group="month",
    series=["California", "Texas"]
    label="Monthly Sales by Region (CA & TX)"
  )
)

Advanced usage

Alternatively, you can pass an object with configuration properties to further customize the series.

Each object must have a value property that can be either a key from your data or a function that receives each row and returns a numeric value.

Node.js

const salesData = [
  { month: "Jan", California: 95, Texas: 120, "New York": 310 },
  { month: "Feb", California: 105, Texas: 135, "New York": 290 },
  /* ... */
  { month: "Dec", California: 250, Texas: 300, "New York": 520 },
];

page.add(() =>
  ui.barChart("sales-chart", salesData, {
    group: "month",
    series: [
        {
            label: "Midwest",
            value: (row) => row.California + row.Texas
        }
    ],
    groupMode: "grouped",
    label: "Monthly Sales by Region",
  })
);

Python

sales_data = [
  { "month": "Jan", "California": 95, "Texas": 120, "New York": 310 },
  { "month": "Feb", "California": 105, "Texas": 135, "New York": 290 },
  # ...
  { "month": "Dec", "California": 250, "Texas": 300, "New York": 520 },
]

def get_midwest(row):
    return row["California"] + row["Texas"]

page.add(() =>
  ui.bar_chart(
    "sales-chart",
    sales_data,
    group="month",
    series=[{
        label: "Midwest",
        value: get_midwest
    }]
    label="Monthly Sales for Midwest"
  )
)

Series object properties

Node.js

value

required string | (row: DataRow, idx: number) => number | null | undefined

The row's value to be used for the series. Either:

• A string that maps to a key in the data.
• A function that receives each row and its index and returns a numeric value. You can also return null or undefined to exclude the row from the dataset.

The returned value will be aggregated by group (e.g. if you are grouping data by month, all rows for a month will be aggregated together).

Python

value

required Callable[[DataRow, int], int | float | None]

The row's value to be used for the series. Either:

• A string that maps to a key in the data.
• A function that receives each row and its index and returns a numeric value. You can also return None to exclude the row from the dataset.

The returned value will be aggregated by group (e.g. if you are grouping data by month, all rows for a month will be aggregated together).

---

Node.js

label

optional string

The label to use for the series in the legend, tooltips, etc.

Python

label

optional str

The label to use for the series in the legend, tooltips, etc.

---

Node.js

aggregate

optional string literal

The aggregate function to be used for the series. Use this if you want this series to be aggregated differently than the others.

Options: sum, count, average, min, max.

Defaults to the chart-level aggregate function (which itself defaults to sum).

Python

aggregate

optional Literal

The aggregate function to be used for the series. Use this if you want this series to be aggregated differently than the others.

Options: sum, count, average, min, max.

Defaults to the chart-level aggregate function (which itself defaults to sum).

---

Kitchen sink example

The example below demonstrates how to create a bar chart with dynamic series and custom grouping.

Node.js

const PRODUCT_TO_COST = {
    "Laptop": 1000,
    "Monitor": 500,
    "Keyboard": 100,
}

const PRODUCTS_LIST = Object.keys(PRODUCT_TO_COST);

const salesData = [
  { date: "2023-01-15", product: "Laptop", },
  { date: "2023-02-22", product: "Monitor", },
  { date: "2023-02-05", product: "Keyboard", },
  /* ... */
  { date: "2023-02-18", product: "Monitor", },
  { date: "2023-03-10", product: "Laptop", },
  { date: "2023-03-25", product: "Monitor", },
];

function getMonth(row) {
  return new Date(row.date).toLocaleString('default', { month: 'short', year: '2-digit' });
}

page.add(() =>
  ui.barChart("monthly-chart", salesData, {
    group: (row) => getMonth(row), // Group the data by month
    series: PRODUCTS_LIST.map(product => ({
        label: product,
        value: (row) => {
            if (row.product === product) {
                return PRODUCT_TO_COST[product];
            }
            return 0;
        }
    })),
    label: "Monthly Revenue by Product"
  })
);

Python

from datetime import datetime

PRODUCT_TO_COST = {
    "Laptop": 1000,
    "Monitor": 500,
    "Keyboard": 100,
}

PRODUCTS_LIST = Object.keys(PRODUCT_TO_COST);

sales_data = [
  { "date": "2023-01-15", "product": "Laptop" },
  { "date": "2023-02-22", "product": "Monitor" },
  { "date": "2023-02-05", "product": "Keyboard" },
  # ...
  { "date": "2023-02-18", "product": "Monitor" },
  { "date": "2023-03-10", "product": "Laptop" },
  { "date": "2023-03-25", "product": "Monitor" },
]

def get_month(row):
  return datetime.strptime(row["date"], "%Y-%m-%d").strftime("%b %y")

def get_series_value(row, product):
    if row["product"] == product:
        return PRODUCT_TO_COST[product]
    return 0

page.add(lambda:
  ui.bar_chart(
    "monthly-chart",
    sales_data,
    group=get_month, # Group the data by month
    series=[
        {
            "label": product,
            "value": lambda row: get_series_value(row, product)
        }
        for product in PRODUCTS_LIST
    ],
    label="Monthly Revenue by Product"
  )
)

API reference

Function signature

Node.js

type DataRow = Record<string, any>

ui.barChart<T extends DataRow>(
    id: string,
    data: T[]
    properties?: Partial<{
        group: string | ((row: T, idx: number) => string | null | undefined),
        series: Array<string | SeriesObject<T>>,
        aggregate: "sum" | "count" | "average" | "min" | "max",
        groupMode: "grouped" | "stacked",
        label: string,
        description: string,
        orientation: "horizontal" | "vertical",
        scale: "linear" | "symlog",
        style: Style,
    }>
)

Python

DataRow = Dict[str, Any]

ui.bar_chart(
    id: str,
    data: List[DataRow],
    *,
    group: str | Callable[[DataRow, int], str | None],
    series: List[str | SeriesObject],
    aggregate: Literal["sum", "count", "average", "min", "max"] = "sum",
    group_mode: Literal["grouped", "stacked"] = "stacked",
    label: str | None = None,
    description: str | None = None,
    orientation: Literal["horizontal", "vertical"] = "vertical",
    scale: Literal["linear", "symlog"] = "linear",
    style: Style,
)

Parameters

Node.js

id

required string

A unique identifier for the component. This is necessary so that Compose can properly pass user actions back to the component.

Python

id

required str

A unique identifier for the component. This is necessary so that Compose can properly pass user actions back to the component.

---

Node.js

data

required DataRow[]

The data to be displayed in the bar chart.

Python

data

required List[DataRow]

The data to be displayed in the bar chart.

---

Node.js

properties.group

optional string | ((row: DataRow, idx: number) => string | null | undefined)

How to group the data. If not provided, Compose will look for a key named group in the data.

Learn more in the group rows section.

Python

group

optional Callable[[DataRow, int], str | None]

How to group the data. If not provided, Compose will look for a key named group in the data.

Learn more in the group rows section.

---

Node.js

properties.series

optional Array<string | SeriesObject>

The series to be displayed in the bar chart. If not provided, Compose will use all keys found in the first row of the data (excluding the group key) as separate series.

Learn more in the series section.

Python

series

optional List[str | SeriesObject]

The series to be displayed in the bar chart. If not provided, Compose will use all keys found in the first row of the data (excluding the group key) as separate series.

Learn more in the series section.

---

Node.js

properties.aggregate

optional string literal

How to aggregate rows that are in the same group. Choose from sum, count, average, min, or max.

Defaults to sum.

Learn more in the aggregate rows section.

Python

aggregate

optional Literal

How to aggregate rows that are in the same group. Choose from sum, count, average, min, or max.

Defaults to sum.

Learn more in the aggregate rows section.

---

Node.js

properties.groupMode

optional string literal

How to display the bars within each group. Either:

• grouped: Display the bars side-by-side.
• stacked: Stack the bars on top of each other.

Defaults to stacked.

Python

group_mode

optional Literal

How to display the bars within each group. Either:

• grouped: Display the bars side-by-side.
• stacked: Stack the bars on top of each other.

Defaults to stacked.

---

Node.js

properties.label

optional string

The label to display above the bar chart. If not provided, the label will be inferred from the id.

Python

label

optional str

The label to display above the bar chart. If not provided, the label will be inferred from the id.

---

Node.js

properties.description

optional string

A description to display between the label and bar chart.

Python

description

optional str

A description to display between the label and bar chart.

---

Node.js

properties.orientation

optional string literal

The orientation of the bar chart. Either:

• horizontal: Display the bars horizontally.
• vertical: Display the bars vertically.

Defaults to vertical.

Python

orientation

optional Literal

The orientation of the bar chart. Either:

• horizontal: Display the bars horizontally.
• vertical: Display the bars vertically.

Defaults to vertical.

---

Node.js

properties.scale

optional string literal

How to scale the value axis. Either:

• linear: Scale linearly. Best for most cases.
• symlog: Scale logarithmically. Best for cases where data differs by orders of magnitude.

Defaults to linear.

Python

scale

optional Literal

How to scale the value axis. Either:

• linear: Scale linearly. Best for most cases.
• symlog: Scale logarithmically. Best for cases where data differs by orders of magnitude.

Defaults to linear.

---

Node.js

properties.style

optional Style

Directly style the underlying element using CSS. See the styling guide for more details on available style properties.

Python

style

optional Style | None

Directly style the underlying element using CSS. See the styling guide for more details on available style properties.

---