Component | Statistic

note

Introduced in SDK v0.26.9

Display a well-formatted, customizable statistic.

TypeScript / JavaScript

ui.row([
  ui.statistic(
    "Total Users",
    135,
    {
      delta: 14,
      description: "Since last month",
      format: "currency",
    },
  ),
  ui.statistic(
    "Total Revenue",
    39211,
    {
      format: "currency",
      delta: .06,
      deltaFormat: "percent",
      description: "Since last month",
    },
  ),
  ui.statistic(
    "At Risk Accounts",
    12,
    {
      delta: -1,
      isPositiveDelta: true,
      description: "Since last month",
      labelColor: "danger",
    },
  ),
])

Python

ui.row([
  ui.statistic(
    "Total Users",
    135,
    delta=14,
    description="Since last month",
    format="currency"
  ),
  ui.statistic(
    "Total Revenue",
    39211,
    format="currency",
    delta=0.06,
    delta_format="percent",
    description="Since last month"
  ),
  ui.statistic(
    "At Risk Accounts",
    12,
    delta=-1,
    is_positive_delta=True,
    description="Since last month",
    label_color="danger"
  )
])

API reference

Function signature

TypeScript / JavaScript

ui.statistic(
    label: string,
    value: number,
    options?: Partial<{
        format: "standard" | "percent" | "currency",
        description: string,
        decimals: number,
        delta: number,
        deltaFormat: "standard" | "percent" | "currency",
        deltaDecimals: number,
        suffix: string,
        prefix: string,
        isPositiveDelta: boolean | ((delta: number) => boolean),
        labelColor: "text" | "text-secondary" | "danger" | "warning" | "success" | "primary",
        valueColor: "text" | "text-secondary" | "danger" | "warning" | "success" | "primary",
        descriptionColor: "text" | "text-secondary" | "danger" | "warning" | "success" | "primary",
        style: Style
    }>
)

Python

ui.statistic(
    label: str,
    value: int | float,
    *,
    format: Literal["standard", "percent", "currency"] = "standard",
    description: str | None = None,
    decimals: int | None = None,
    delta: int | float | None = None,
    delta_format: Literal["standard", "percent", "currency"] = "standard",
    delta_decimals: int | None = None,
    is_positive_delta: bool | None = None,
    suffix: str | None = None,
    prefix: str | None = None,
    label_color: Literal["text", "text-secondary", "danger", "warning", "success", "primary"] = "text",
    value_color: Literal["text", "text-secondary", "danger", "warning", "success", "primary"] = "text",
    description_color: Literal["text", "text-secondary", "danger", "warning", "success", "primary"] = "text-secondary",
    style: Style | None = None,
)

Parameters

TypeScript / JavaScript

label

required string

The title of the statistic.

Python

label

required str

The title of the statistic.

---

TypeScript / JavaScript

value

required number

The value of the statistic.

Python

value

required int | float

The value of the statistic.

---

TypeScript / JavaScript

properties.format

optional string literal

The format to display the value in. Defaults to "standard".

Options:

• "standard": Display the value as a standard number.
• "percent": Display the value as a percentage.
• "currency": Display the value as a currency.

Python

format

optional Literal

The format to display the value in. Defaults to "standard".

Options:

• "standard": Display the value as a standard number.
• "percent": Display the value as a percentage.
• "currency": Display the value as a currency.

---

TypeScript / JavaScript

properties.description

optional string

Display an optional description below the value.

Python

description

optional str

Display an optional description below the value.

---

TypeScript / JavaScript

properties.decimals

optional number

Round the value to the specified number of decimal places. By default, the value is not rounded.

Python

decimals

optional int

Round the value to the specified number of decimal places. By default, the value is not rounded.

---

TypeScript / JavaScript

properties.delta

optional number

Display a delta value to represent the change in the value.

Python

delta

optional int | float

Display a delta value to represent the change in the value.

---

TypeScript / JavaScript

properties.deltaFormat

optional string literal

The format to display the delta in. Defaults to "standard".

Options:

• "standard": Display the delta as a standard number.
• "percent": Display the delta as a percentage.
• "currency": Display the delta as a currency.

Python

delta_format

optional Literal

The format to display the delta in. Defaults to "standard".

Options:

• "standard": Display the delta as a standard number.
• "percent": Display the delta as a percentage.
• "currency": Display the delta as a currency.

---

TypeScript / JavaScript

properties.deltaDecimals

optional number

Round the delta to the specified number of decimal places. By default, the delta is not rounded.

Python

delta_decimals

optional int

Round the delta to the specified number of decimal places. By default, the delta is not rounded.

---

TypeScript / JavaScript

properties.isPositiveDelta

optional boolean | ((delta: number) => boolean)

Override the default determination of whether the delta is positive or negative with custom logic. By default, the delta is positive if it is greater than 0, and negative if it is less than 0.

Python

is_positive_delta

optional bool | Callable[[int, float], bool]

Override the default determination of whether the delta is positive or negative with custom logic. By default, the delta is positive if it is greater than 0, and negative if it is less than 0.

---

TypeScript / JavaScript

properties.suffix

optional string

Display an optional suffix to the value. This will override any default suffix that would otherwise be applied based on the format option.

Python

suffix

optional str

Display an optional suffix to the value. This will override any default suffix that would otherwise be applied based on the format option.

---

TypeScript / JavaScript

properties.prefix

optional string

Display an optional prefix to the value. This will override any default prefix that would otherwise be applied based on the format option.

Python

prefix

optional str

Display an optional prefix to the value. This will override any default prefix that would otherwise be applied based on the format option.

---

TypeScript / JavaScript

properties.labelColor

optional string literal

Specifies the color of the label. Defaults to "text"

Options:

• "text": Default text color
• "text-secondary": Secondary text color, uses a lighter shade of the default text color
• "primary": Primary color. Defaults to a shade of blue. Can be set via the theme.
• "success": Success color, green.
• "warning": Warning color, orange.
• "danger": Danger color, red.
• "background": Background color. Can be used over inverted backgrounds.

Python

label_color

optional Literal

Specifies the color of the label. Defaults to "text"

Options:

• "text": Default text color
• "text-secondary": Secondary text color, uses a lighter shade of the default text color
• "primary": Primary color. Defaults to a shade of blue. Can be set via the theme.
• "success": Success color, green.
• "warning": Warning color, orange.
• "danger": Danger color, red.
• "background": Background color. Can be used over inverted backgrounds.

---

TypeScript / JavaScript

properties.valueColor

optional string literal

Specifies the color of the value. Defaults to "text"

Options:

• "text": Default text color
• "text-secondary": Secondary text color, uses a lighter shade of the default text color
• "primary": Primary color. Defaults to a shade of blue. Can be set via the theme.
• "success": Success color, green.
• "warning": Warning color, orange.
• "danger": Danger color, red.
• "background": Background color. Can be used over inverted backgrounds.

Python

value_color

optional Literal

Specifies the color of the value. Defaults to "text"

Options:

• "text": Default text color
• "text-secondary": Secondary text color, uses a lighter shade of the default text color
• "primary": Primary color. Defaults to a shade of blue. Can be set via the theme.
• "success": Success color, green.
• "warning": Warning color, orange.
• "danger": Danger color, red.
• "background": Background color. Can be used over inverted backgrounds.

---

TypeScript / JavaScript

properties.descriptionColor

optional string literal

Specifies the color of the description. Defaults to "text-secondary"

Options:

• "text": Default text color
• "text-secondary": Secondary text color, uses a lighter shade of the default text color
• "primary": Primary color. Defaults to a shade of blue. Can be set via the theme.
• "success": Success color, green.
• "warning": Warning color, orange.
• "danger": Danger color, red.
• "background": Background color. Can be used over inverted backgrounds.

Python

description_color

optional Literal

Specifies the color of the description. Defaults to "text-secondary"

Options:

• "text": Default text color
• "text-secondary": Secondary text color, uses a lighter shade of the default text color
• "primary": Primary color. Defaults to a shade of blue. Can be set via the theme.
• "success": Success color, green.
• "warning": Warning color, orange.
• "danger": Danger color, red.
• "background": Background color. Can be used over inverted backgrounds.

---

TypeScript / JavaScript

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.

---