> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ProgressBar

> Show measured or indeterminate progress with a horizontal bar.

export const StoryEmbed = ({storyId, title, height = 120}) => <>
    <Tabs>
      <Tab title="Light">
        <iframe title={`${title} (light)`} src={`https://storybook.twenty.com/iframe.html?id=${storyId}&viewMode=story&globals=colorScheme:light`} width="100%" height={height} loading="lazy" allow="clipboard-write" style={{
  border: 0
}} />
      </Tab>
      <Tab title="Dark">
        <iframe title={`${title} (dark)`} src={`https://storybook.twenty.com/iframe.html?id=${storyId}&viewMode=story&globals=colorScheme:dark`} width="100%" height={height} loading="lazy" allow="clipboard-write" style={{
  border: 0
}} />
      </Tab>
    </Tabs>
    <a href={`https://storybook.twenty.com/?path=/story/${storyId}`}>
      Open in Storybook
    </a>
  </>;

`ProgressBar` supplies a horizontal appearance for [Progress](/ui/primitives/feedback/progress). It preserves the complete root contract, including native attributes, refs, render composition, formatting, custom ranges, and indeterminate progress. Give it an `aria-label` that identifies the operation.

<StoryEmbed storyId="ui-feedback-progressbar-progressbar--display" title="ProgressBar example" height={100} />

## Usage

```tsx theme={null}
import { ProgressBar } from 'twenty-ui/primitives/feedback';
import { Text } from 'twenty-ui/primitives/typography';

type ImportProgressProps = { importedRecords: number | null };

export const ImportProgress = ({ importedRecords }: ImportProgressProps) => (
  <Text style={{ display: 'grid', gap: 8, width: 300 }}>
    <Text>Importing records: {importedRecords ?? 'preparing'}</Text>
    <ProgressBar
      value={importedRecords}
      max={1000}
      aria-label="Importing records"
    />
  </Text>
);
```

## State ownership and ranges

`value` is required and controlled by the application. There is no `defaultValue` mode. The component does not start a request or advance progress by itself. Pass `null` when progress is unknown. Non-finite values also remain indeterminate.

`min` defaults to `0`, and `max` defaults to `100`. Finite values are clamped to the range for the semantic value and normalized fill. A value of `70` in the range `20` to `120` fills half the bar and reports `50%`, while `aria-valuenow` stays `70`.

<StoryEmbed storyId="ui-feedback-progressbar-progressbar--custom-range" title="A nonzero minimum and custom maximum" height={80} />

Use `aria-valuetext`, `getAriaValueText`, `locale`, and `format` as described in [Progress](/ui/primitives/feedback/progress). Use composed Progress parts when labels and values need their own visible layout.

Use [Toast](/ui/components/feedback/toast) for notifications with a dismiss countdown and hover pause.

## Appearance and composition

`size` selects a 6px or 8px track. `barColor` and `backgroundColor` accept CSS colors, including theme variables. `withBorderRadius` rounds the track and indicator. `withMinimumFillWidth` keeps a small cosmetic fill only between the minimum and completion. This minimum is at most 12px and half the track width, so a narrow track still distinguishes incomplete progress from completion. It does not fill an empty bar or change semantic values.

Native attributes, `className`, `style`, and `ref` target the root. `className` and `style` can receive the progress state. `render` can replace the root while preserving its semantics. Indeterminate progress has its own appearance without reporting a numeric percentage. Reduced-motion preferences disable fill transitions and indeterminate motion.

Compose [Progress parts](/ui/primitives/feedback/progress) for custom layouts or feature animation. Feature timing, grow-in, glints, springs, and completion callbacks belong to the application composition.

## Migration

Replace `ariaLabel` with native `aria-label`. The `withGrowIn`, `withGlint`, `withSpringFill`, and `onGrowInComplete` props are removed. Implement their appearance, timing, and completion callbacks in an application composition using [Progress parts](/ui/primitives/feedback/progress). Native `onAnimationEnd` remains available on the root.

## Props

<ParamField body="aria-label" type="string">
  Accessible name identifying the measured operation.
</ParamField>

<ParamField body="aria-labelledby" type="string">
  ID of the visible label that names the operation.
</ParamField>

<ParamField body="aria-valuetext" type="string">
  Human-readable progress value overriding the default formatted value.
</ParamField>

<ParamField body="backgroundColor" type="string" default="none">
  CSS background color of the track.
</ParamField>

<ParamField body="barColor" type="string">
  CSS color of the filled bar. Defaults to the primary text color.
</ParamField>

<ParamField body="children" type="ReactNode">
  Additional Progress parts or supporting content inside the root.
</ParamField>

<ParamField body="className" type="string | ((state: ProgressRootState) => string | undefined)">
  Class applied to the progress root, or a callback receiving its status.
</ParamField>

<ParamField body="format" type="NumberFormatOptions">
  Intl.NumberFormat options for the clamped numeric value. The default displays the normalized percentage.
</ParamField>

<ParamField body="getAriaValueText" type="((formattedValue: string, value: number | null) => string)">
  Receives the formatted value and raw value, including null, and returns an accessible value description.
</ParamField>

<ParamField body="locale" type="LocalesArgument">
  Locale or locale list used to format the value. Defaults to the runtime locale.
</ParamField>

<ParamField body="max" type="number" default="100">
  Inclusive maximum. Defaults to 100.
</ParamField>

<ParamField body="min" type="number" default="0">
  Inclusive minimum. Defaults to 0.
</ParamField>

<ParamField body="ref" type="Ref<HTMLDivElement>">
  Ref to the root div, or the element composed through render.
</ParamField>

<ParamField body="render" type="ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ProgressRootState>">
  Composes the root with an element or render callback. Forward the supplied props and ref to retain progress semantics.
</ParamField>

<ParamField body="size" type="&#x22;md&#x22; | &#x22;sm&#x22;" default="md">
  Bar height: sm (6px) or md (8px).
</ParamField>

<ParamField body="style" type="CSSProperties | ((state: ProgressRootState) => CSSProperties | undefined)">
  Inline styles applied to the progress root, or a callback receiving its status.
</ParamField>

<ParamField body="value" type="number | null" required>
  Controlled value in the min/max range. Use null for indeterminate progress.
</ParamField>

<ParamField body="withBorderRadius" type="boolean" default="false">
  Rounds the track and indicator corners.
</ParamField>

<ParamField body="withMinimumFillWidth" type="boolean" default="true">
  Applies a cosmetic minimum of up to 12px, capped at half the track width, only above the minimum and below completion.
</ParamField>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.