Circular Progress

Tips & examples

A circular track progress ring featuring a hollow layout center that highlights the percentage status directly in the middle as a formatted number.

When to use

Visualizing statistical percentages, metrics, or completion rates bounded strictly between 0 and 100.
Displaying progress tracking metrics cleanly within dashboard grid cells, panels, or summary headers.

What you need

Integer metrics, query outputs containing aggregate values, or computational scores evaluated in expression mode.

Examples

A storage dashboard element showing ‘75% storage capacity utilized’.
A learning management portal tracking a student’s ‘45% course completion rate’.

Avoid

Using for unconstrained values or numbers outside the 0–100 percentage range (e.g. currency amounts, raw unit counts, or negative numbers), which distorts the circular ring calculation.
Setting an extreme Thickness (e.g., near 40) paired with a small container Size or a large typography Variant (e.g., ‘h1’), which causes the center percentage text to overflow or overlap the ring stroke.
Using as an interactive input element where users are expected to drag or click to adjust a metric, use a slider or number input component instead.

Properties

Editor properties

Configure these in the Application Designer property panel. Group headings mirror the editor where possible. Data Source is where the element gets its rows or field binding (a view/query, a connector operation, or a parent form field). References appear only for view-backed sources and map foreign-key ID columns to readable labels from another view.

Value

ValuerequiredCustom expression: An integer representation of the progress state between 0 and 100. Can be parsed directly from database fields or computed live.
Example 75
Default: buildCustomExpressionValue("75")

Styling

SizeoptionalText or Number

An integer determining the overall pixel footprint diameter bounding box of the circular ring.

Default: DEFAULTS.size

ThicknessoptionalNumber

An integer constraint restricted strictly from 0 to 40 that configures the physical stroke weight width of the progress ring perimeter line.

Default: DEFAULTS.thickness

ColoroptionalOne of: primary, secondary, inherit

Sets the visual indicator theme context layer palette application.

Choices

primary — Theme default signature branding highlight color.
secondary — Theme default secondary supporting color palette accent.
inherit — Cascades color property tokens directly down from its nearest matching parent layout layer wrapper.

Default: DEFAULTS.color

VariantoptionalOne of: h1, h2, h3, h4, h5, h6, subtitle1, subtitle2, body1, caption, button, overline

Controls the typography scaling and font weight parameters applied to the center metric value text layout.

Choices

h1 — Extra large display headline text scaling.
h2 — Large display title text scaling.
h3 — Medium headline typography size spacing.
h4 — Standard section header text scale layout.
h5 — Compact sub-header text block scaling parameters.
h6 — Minimal header typography weight spacing.
subtitle1 — Primary bold layout descriptor accent scaling.
subtitle2 — Secondary compact label style font footprint.
body1 — Standard text size proportions.
caption — Small low-contrast utility text formatting scale.
button — Stylized block layout indicator weight rules.
overline — All-caps tracking format layout styling rules.

Default: DEFAULTS.variant

Sizing

No size of its own: dropped at the platform default of 1 × 1 grid cells and resized on the page.

Translatable labels

label — Text block string detailing the contextual tracking background meaning of the progress ring.

Composition

Where you can place it

Drag this element into one of these containers:

Sample configuration

Minimal example — required fields only ↕

1
2
3
4
5
{
  "config": {
    "value": "@@expression:'value'"
  }
}

1
2
3
4
5
6
7
8
9
{
  "config": {
    "value": "@@expression:'value'",
    "size": "size",
    "thickness": 0,
    "color": "primary",
    "variant": "h1"
  }
}

Ready-made setups

Dashboard Metric Ring Indicator ↕

Configuring a clean metric percentage dashboard chart utilizing thick outlines and standard body text typography configurations.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
  "config": {
    "value": {
      "valueExpression": "@@expression: 85"
    },
    "styling": {
      "size": 120,
      "thickness": 8,
      "color": "primary",
      "variant": "h4"
    }
  }
}

Notes

Description

The CircularProgress is used to display a progress value between 0 and 100.

config

property	type	description	required
`value`	`number`	The value to display (between 0 and 100)	✔️
`size`	`number	string`	The size of the element
`thickness`	`number`	How thick the line is
`color`	`“primary”	“secondary”	“inherit”`

i18n

name	description	required
label	Text displayed in the middle of the circle