Progress, status & badges

5 min · Pattern

ProgressBar for completion, StatusIndicator for state dots, and Badge for counts and labels — the three primitives for showing where things stand.

What this pattern covers

Users need to see progress and state at a glance:

ProgressBar — upload progress, onboarding steps, storage usage
StatusIndicator — online/offline dots, kanban status, sync state
Badge — notification counts, version labels, category chips

These appear in dashboards, settings, roadmaps, and navigation — often together on the same row.

ProgressBar

ProgressBar renders a filled track with an optional animated percentage label.

Prop	Default	Use for
`value`	required	Current value (0–100 or custom range)
`min` / `max`	0 / 100	Custom scales (e.g. 0–5 GB)
`label`	`true`	Show percentage text
`labelPosition`	`"bottom"`	`"top"`, `"bottom"`, `"left"`, `"right"`
`barBackground`	`"brand-strong"`	Fill color token

The label uses an animated counter internally — you only pass the numeric value.

Storage usage example

<Column gap="8" fillWidth>
  <Row fillWidth horizontal="between" vertical="center">
    <Text variant="body-strong-s">Storage</Text>
    <Text variant="label-default-s" onBackground="neutral-weak">
      7.2 GB of 10 GB
    </Text>
  </Row>
  {/* ProgressBar value={72} barBackground="brand-strong" */}
</Column>

Onboarding checklist

Stack multiple ProgressBar rows — one per step — with labelPosition="right" for a compact sidebar widget. Hide the label (label={false}) when the surrounding Text already states the percentage.

StatusIndicator

StatusIndicator is a small colored dot. Use it anywhere a word label would be too heavy.

Color	Typical meaning
`green` / `emerald`	Online, success, complete
`brand`	In progress, active
`red` / `orange`	Error, blocked, warning
`gray` / `neutral`	Offline, inactive, planned
`yellow`	Pending, attention needed

Sizes follow t-shirt tokens: xs, s, m (default), l. Pair with a Text label in a Row:

<Row gap="8" vertical="center">
  {/* StatusIndicator color="green" size="s" ariaLabel="Online" */}
  <Text variant="label-default-s">Online</Text>
</Row>

Always set ariaLabel when the dot appears without adjacent text.

In tables and lists

Add a StatusIndicator column for row state — sync status, deployment health, user presence. Keep the dot in dense tables.

5 min · Pattern

ProgressBar for completion, StatusIndicator for state dots, and Badge for counts and labels — the three primitives for showing where things stand.

What this pattern covers

Users need to see progress and state at a glance:

ProgressBar — upload progress, onboarding steps, storage usage
StatusIndicator — online/offline dots, kanban status, sync state
Badge — notification counts, version labels, category chips

These appear in dashboards, settings, roadmaps, and navigation — often together on the same row.

ProgressBar

ProgressBar renders a filled track with an optional animated percentage label.

Prop	Default	Use for
`value`	required	Current value (0–100 or custom range)
`min` / `max`	0 / 100	Custom scales (e.g. 0–5 GB)
`label`	`true`	Show percentage text
`labelPosition`	`"bottom"`	`"top"`, `"bottom"`, `"left"`, `"right"`
`barBackground`	`"brand-strong"`	Fill color token

The label uses an animated counter internally — you only pass the numeric value.

Storage usage example

<Column gap="8" fillWidth>
  <Row fillWidth horizontal="between" vertical="center">
    <Text variant="body-strong-s">Storage</Text>
    <Text variant="label-default-s" onBackground="neutral-weak">
      7.2 GB of 10 GB
    </Text>
  </Row>
  {/* ProgressBar value={72} barBackground="brand-strong" */}
</Column>

Onboarding checklist

Stack multiple ProgressBar rows — one per step — with labelPosition="right" for a compact sidebar widget. Hide the label (label={false}) when the surrounding Text already states the percentage.

StatusIndicator

StatusIndicator is a small colored dot. Use it anywhere a word label would be too heavy.

Color	Typical meaning
`green` / `emerald`	Online, success, complete
`brand`	In progress, active
`red` / `orange`	Error, blocked, warning
`gray` / `neutral`	Offline, inactive, planned
`yellow`	Pending, attention needed

Sizes follow t-shirt tokens: xs, s, m (default), l. Pair with a Text label in a Row:

<Row gap="8" vertical="center">
  {/* StatusIndicator color="green" size="s" ariaLabel="Online" */}
  <Text variant="label-default-s">Online</Text>
</Row>

Always set ariaLabel when the dot appears without adjacent text.

In tables and lists

Add a StatusIndicator column for row state — sync status, deployment health, user presence. Keep the dot in dense tables.

Prop	Notes
`children`	Badge text — do not duplicate in `title`
`icon`	Optional leading IconName
`href`	Makes badge a link; enables arrow by default
`effect`	Subtle shine animation (default `true`)

<Column
  background="surface"
  border="neutral-alpha-weak"
  radius="l"
  padding="24"
  gap="16"
  fillWidth
>
  <Row fillWidth horizontal="between" vertical="center">
    <Row gap="8" vertical="center">
      {/* StatusIndicator color="green" size="s" */}
      <Text variant="body-strong-s">Production</Text>
    </Row>
    {/* Badge children="v2.4.1" */}
  </Row>
  {/* ProgressBar value={100} label={false} */}
  <Text variant="body-default-xs" onBackground="neutral-weak">
    All instances updated
  </Text>
</Column>

✅ Once UI way	❌ Common mistake
ProgressBar with token `barBackground`	Inline width div with hex color
StatusIndicator + label Text	Color-only dot with no accessible name
Badge `children` for text	Same text in `title` and `children`
`label={false}` when context is obvious	Redundant percentage everywhere

What this pattern covers

ProgressBar

Storage usage example

Onboarding checklist

StatusIndicator

In tables and lists

What this pattern covers

ProgressBar

Storage usage example

Onboarding checklist

StatusIndicator

In tables and lists

Badge

Combining all three

Write this / not this

Check yourself

Progress, status & badges

What this pattern covers

ProgressBar

Storage usage example

Onboarding checklist

StatusIndicator

In tables and lists

What this pattern covers

ProgressBar

Storage usage example

Onboarding checklist

StatusIndicator

In tables and lists

Badge

Combining all three

Write this / not this

Check yourself

Related