Progress

01Preview

Change the controls to try every supported combination of Progress and CircularProgress. The preview renders the real component and the code updates with it.

import { Progress } from '@nuton/ui'

<Progress
  value={60}
  label="Course completion"
  description="6 of 10 lessons finished"
/>

02Installation

1. Add the packages

pnpm add @nuton/ui @nuton/tokens

npm install @nuton/ui @nuton/tokens

yarn add @nuton/ui @nuton/tokens

Peer dependencies: react and react-dom 18 or later. Progress needs no icons.

2. Load tokens and component styles once

// app/layout.tsx (or your app's entry file)
import '@nuton/tokens/tokens.css' // --nu-* design tokens
import '@nuton/ui/styles.css'     // component styles (uses the tokens)

The title, value and description use --nu-font-body (Inter). Map the token to your loaded font, as described on the Button page.

03Usage

import { Progress } from '@nuton/ui'

export function CourseProgress({ done, total }: { done: number; total: number }) {
  return (
    <Progress
      value={done}
      max={total}
      label="Introduction to biology"
      description={`${done} of ${total} lessons finished`}
    />
  )
}

• value is required and runs from 0 to max (default 100). Values outside the range are clamped, so you can pass raw counts.
• Every progress bar needs a name: label on Progress, or aria-label / aria-labelledby. CircularProgress has no label prop, so it always needs an ARIA name.
• The visible value defaults to a whole percentage, formatted in English so server and browser render the same text. Use formatValue for counts such as “3 of 8 lessons”; it also sets what screen readers hear.
• Use the bar inside cards, lists and forms; use the ring where space is square, such as a course tile or a dashboard stat.
• Progress needs a known value. There's no indeterminate mode yet (C41): for a wait with no known end, use a Button's loading state.

04Variants and sizes

Progress is the bar and CircularProgress is the ring. Both share value, max, color and formatValue. The bar adds a title row and an optional bottom row; the ring adds five sizes.

Colours

<Progress value={60} label="Blue" />                  // default
<Progress value={60} color="red" label="Red" />
<Progress value={60} color="orange" label="Orange" />
<Progress value={60} color="green" label="Green" />
<Progress value={0} color="empty" label="Not started" />   // fill matches the track

The track is always --nu-bg-soft-200. Pair a colour with words in the title or description; colour alone doesn't say what changed.

Label position

<Progress value={40} label="Weekly goal" />                       // top (default)
<Progress value={40} label="Weekly goal" labelPosition="right" /> // title visually hidden

With labelPosition="right", Figma shows no title, so label is rendered visually hidden: it still names the bar for screen readers. The bottom row isn't shown in this layout (C41).

Description and action

<Progress
  value={72}
  color="orange"
  label="Space storage"
  description="Upgrade to keep adding lesson videos."
  action={<LinkButton href="/settings/storage" tone="primary" size="sm">Manage storage</LinkButton>}
/>

The bottom row is linked to the bar with aria-describedby. The action sits before the description, as in Figma. To show a value such as “7.2 GB of 10 GB” instead of a percentage, see Value format.

Value format and maximum

<Progress
  value={3}
  max={8}
  label="Cell biology"
  formatValue={(value, max) => `${value} of ${max} lessons`}
  description="Next: Mitosis and meiosis"
/>
<CircularProgress
  value={18}
  max={24}
  size={72}
  color="green"
  formatValue={(value, max) => `${value}/${max}`}
  aria-label="Quiz score"
/>

Ring sizes

<CircularProgress value={75} aria-label="Course completion" />            // 80, default
<CircularProgress value={75} size={72} aria-label="Course completion" />
<CircularProgress value={75} size={64} aria-label="Course completion" />
<CircularProgress value={75} size={56} aria-label="Course completion" />
<CircularProgress value={75} size={48} aria-label="Course completion" /> // no number

Dimensions

Taken from the component CSS, which follows Figma's geometry. Ring thickness comes from Figma's inner radius: 0.84 of the radius for sizes 80 to 56, and 0.72 at 48. The ring starts at the top and fills clockwise, with square ends.

05States and interactions

Progress isn't interactive, so it has no hover, focus or disabled state. Its states are the values it shows.

Tokens

The colour prop sets these custom properties. Override them on a wrapper only for a documented exception.

06Composition examples

Course tile

The ring sits beside a visible heading, which names it through aria-labelledby, so the name isn't repeated.

<div className="course-tile">
  <CircularProgress value={64} size={64} aria-labelledby="course-chemistry" />
  <div>
    <strong id="course-chemistry">Organic chemistry</strong>
    <span>7 of 11 lessons · Next: Alkenes</span>
  </div>
</div>

Lesson list

Use labelPosition="right" in dense rows. The visually hidden label still names each bar.

<ul className="lesson-list">
  <li>
    <span>Photosynthesis</span>
    <Progress value={100} color="green" label="Photosynthesis" labelPosition="right" />
  </li>
  <li>
    <span>Cellular respiration</span>
    <Progress value={50} label="Cellular respiration" labelPosition="right" />
  </li>
  <li>
    <span>The nitrogen cycle</span>
    <Progress value={0} label="The nitrogen cycle" labelPosition="right" />
  </li>
</ul>

Multi-step setup

For a short sequence, count steps with max and formatValue. The description names the current step.

const steps = ['Choose your subjects', 'Set a weekly goal', 'Join a space', 'Start your first lesson']

<Progress
  value={step}
  max={steps.length}
  label="Set up your learning space"
  formatValue={(value, max) => `Step ${value} of ${max}`}
  description={steps[step - 1]}
/>
<Button size="sm" appearance="stroke" disabled={step === 1} onClick={back}>Back</Button>
<Button size="sm" onClick={next}>{step === steps.length ? 'Start over' : 'Next'}</Button>

File uploads

Each File upload item already contains a Progress bar, named by the file name. Don't add another one beside it.

07API reference

Progress props

CircularProgress props

Styling hooks

Progress renders .nu-progress with data-label-position and data-color; the bar is .nu-progress__track. CircularProgress renders .nu-circular-progress with data-size and data-color. Use props rather than styling these. The tokens in Tokens are the supported override points.

Accessibility

You must: name every bar (label, aria-label or aria-labelledby); say in words when a task completes or fails; keep formatValue text meaningful on its own.

Figma mapping

The value and description bind a remote Text/Sub-600; code uses the local --nu-text-sub-600, which has the same value.

08Guidelines and related components

Do and don't

Common mistakes

• Leaving CircularProgress without aria-label or aria-labelledby. It has no label prop.
• Faking an indeterminate state by looping the value from 0 to 100. Screen readers announce a value that means nothing.
• Passing a description or action with labelPosition="right". They aren't shown in that layout.
• Writing a formatValue that returns only a number (“3”). It's also the screen reader text, so include the unit.

Related components

• File uploadUpload cards that show each file’s progress.
• ButtonThe loading state, for waits with no known end.
• Link buttonThe action in the progress bar’s bottom row.
• ColourThe state colours behind each fill.