Progress

Progress exposes the installed Base UI parts: Root, Track, Indicator, Label, and Value. Import them from twenty-ui/primitives/feedback. Use ProgressBar or ProgressRing for a convenient appearance with the same semantic contract.

Compose progress

Root owns the controlled value and accessible progressbar semantics. Label supplies its accessible name. Value displays the formatted value. Track and Indicator describe the visual fill; the indicator width comes from the root’s normalized range. The parts do not impose an appearance.

import { Progress } from 'twenty-ui/primitives/feedback';

export const ImportProgress = () => (
  <Progress.Root value={70} min={20} max={120} style={{ width: 240 }}>
    <Progress.Label>Importing records</Progress.Label>
    <Progress.Value />
    <Progress.Track
      style={{ height: 8, background: 'var(--t-background-tertiary)' }}
    >
      <Progress.Indicator
        style={{ background: 'var(--t-font-color-primary)' }}
      />
    </Progress.Track>
  </Progress.Root>
);

This range displays 50% while aria-valuenow is 70, aria-valuemin is 20, and aria-valuemax is 120. The application owns requests, timing, and progress updates. There is no defaultValue or automatic advancement.

Values, ranges, and indeterminate progress

min defaults to 0, and max defaults to 100. Supply finite bounds with min < max. Finite values outside the range are clamped for the semantic value, formatted value, and visual fill. Completion occurs at the maximum. Changing the range recalculates the percentage without changing the raw value supplied by the application. Pass value={null} when the amount of progress is unknown. The root then has indeterminate status, omits aria-valuenow, and uses indeterminate progress as its default accessible value text. Non-finite values also remain indeterminate; they are not converted to zero. The raw Indicator has no computed percentage width in that state, so the composition chooses its indeterminate appearance.

import { ProgressBar } from 'twenty-ui/primitives/feedback';

export const PendingImport = () => (
  <ProgressBar value={null} aria-label="Preparing the import" />
);

Labels and formatting

Compose Progress.Label inside Root, or set native aria-label or aria-labelledby. Use aria-valuetext for a human-readable alternative when a percentage is insufficient. The default formatter displays the normalized percentage. locale and format retain the installed Intl.NumberFormat contract; an explicit format formats the clamped numeric value. getAriaValueText(formattedValue, value) receives that formatted text and the raw application value, including null. It changes the accessible value text without changing the fill.

import { Progress } from 'twenty-ui/primitives/feedback';

export const RecordCount = () => (
  <Progress.Root
    value={600}
    max={1000}
    format={{ style: 'decimal' }}
    getAriaValueText={(formattedValue) => `${formattedValue} of 1,000 records`}
  >
    <Progress.Label>Importing records</Progress.Label>
    <Progress.Value>
      {(formattedValue) => `${formattedValue} / 1,000`}
    </Progress.Value>
  </Progress.Root>
);

Progress.Value receives both the formatted value and raw value through its optional child callback. For indeterminate progress, the callback receives indeterminate as formatted text; without a callback, the value part displays no content. Display content does not automatically become the accessible name or accessible value text.

Native props, refs, and composition

Part	Default DOM and ref target
`Root`	Outer `div` with progressbar semantics
`Track`	Track `div`
`Indicator`	Fill `div`
`Label`	Label `span`
`Value`	Value `span`

Every part preserves native props, refs, and the installed render composition contract. Forward the supplied props and ref when replacing an element. className, style, and render callbacks receive the public state with status: progressing, complete, or indeterminate. State attributes make the same status available to styles. The entry point exports ProgressStatus and the Props and State types for every part, including ProgressRootProps, ProgressRootState, ProgressIndicatorProps, and ProgressIndicatorState. Each part forwards native event handlers. Applications own feature choreography and completion callbacks.

Props

Progress.Root

string

Accessible name identifying the measured operation.

string

ID of the visible label that names the operation.

string

Human-readable progress value overriding the default formatted value.

ReactNode

Composed Progress parts and supporting content.

string | ((state: ProgressRootState) => string | undefined)

Class applied to this part, or a callback receiving its progress status.

NumberFormatOptions

Intl.NumberFormat options for the clamped numeric value. The default displays the normalized percentage.

((formattedValue: string, value: number | null) => string)

Receives the formatted value and raw value, including null, and returns an accessible value description.

LocalesArgument

Locale or locale list used to format the value. Defaults to the runtime locale.

number

default:"100"

Inclusive maximum. Defaults to 100.

number

default:"0"

Inclusive minimum. Defaults to 0.

Ref<HTMLDivElement>

Ref to the root div, or the element composed through Root.render.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ProgressRootState>

Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element.

CSSProperties | ((state: ProgressRootState) => CSSProperties | undefined)

Inline styles applied to this part, or a callback receiving its progress status.

number | null

required

Controlled value in the min/max range. Use null for indeterminate progress.

Progress.Track

ReactNode

The indicator and optional supporting content.

string | ((state: ProgressTrackState) => string | undefined)

Class applied to this part, or a callback receiving its progress status.

Ref<HTMLDivElement>

Ref to the track div, or the element composed through Track.render.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ProgressTrackState>

Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element.

CSSProperties | ((state: ProgressTrackState) => CSSProperties | undefined)

Inline styles applied to this part, or a callback receiving its progress status.

Progress.Indicator

string | ((state: ProgressIndicatorState) => string | undefined)

Class applied to this part, or a callback receiving its progress status.

Ref<HTMLDivElement>

Ref to the indicator div, or the element composed through Indicator.render.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ProgressIndicatorState>

Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element.

CSSProperties | ((state: ProgressIndicatorState) => CSSProperties | undefined)

Inline styles applied to this part, or a callback receiving its progress status.

Progress.Value

((formattedValue: string | null, value: number | null) => ReactNode) | null

Optional callback receiving the formatted value and raw value. Indeterminate progress passes indeterminate as formatted text. Without a callback, indeterminate progress displays no content.

string | ((state: ProgressValueState) => string | undefined)

Class applied to this part, or a callback receiving its progress status.

Ref<HTMLSpanElement>

Ref to the value span, or the element composed through Value.render.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ProgressValueState>

Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element.

CSSProperties | ((state: ProgressValueState) => CSSProperties | undefined)

Inline styles applied to this part, or a callback receiving its progress status.

Progress.Label

ReactNode

Visible text that supplies the accessible name of the root.

string | ((state: ProgressLabelState) => string | undefined)

Class applied to this part, or a callback receiving its progress status.

Ref<HTMLSpanElement>

Ref to the label span, or the element composed through Label.render.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ProgressLabelState>

Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element.

CSSProperties | ((state: ProgressLabelState) => CSSProperties | undefined)

Inline styles applied to this part, or a callback receiving its progress status.

Overview

Apps

API

Self-Host

Contribute

UI Library

Compose progress

Values, ranges, and indeterminate progress

Labels and formatting

Native props, refs, and composition

Props

Progress.Root

Progress.Track

Progress.Indicator

Progress.Value

Progress.Label

​Compose progress

​Values, ranges, and indeterminate progress

​Labels and formatting

​Native props, refs, and composition

​Props

​Progress.Root

​Progress.Track

​Progress.Indicator

​Progress.Value

​Progress.Label

Compose progress

Values, ranges, and indeterminate progress

Labels and formatting

Native props, refs, and composition

Props

Progress.Root

Progress.Track

Progress.Indicator

Progress.Value

Progress.Label