# Progress - Linear

URL: https://ark-ui.com/docs/components/progress-linear
Source: https://raw.githubusercontent.com/chakra-ui/ark/refs/heads/main/website/src/content/pages/components/progress-linear.mdx

An element that shows either determinate or indeterminate progress.

---

<ComponentPreview id="ProgressLinear" />

## Anatomy

To set up the progress correctly, you'll need to understand its anatomy and how we name its parts.

> Each part includes a `data-part` attribute to help identify them in the DOM.

<Anatomy id="linear-progress" />

## Examples

Learn how to use the `Progress` component in your project. Let's take a look at the most basic example:

<Example id="basic" />

### Set a min and max value

By default, the maximum is `100`. If that's not what you want, you can easily specify a different bound by changing the
value of the `max` prop. You can do the same with the minimum value by setting the `min` prop.

For example, to show the user a progress from `10` to `30`, you can use:

<Example id="min-max" />

### Indeterminate progress

The progress component is determinate by default, with the value and max set to 50 and 100 respectively. To render an
indeterminate progress, you will have to set the `value` to `null`.

<Example id="indeterminate" />

### Showing a value text

Progress bars can only be interpreted by sighted users. To include a text description to support assistive technologies
like screen readers, use the `value` part in `translations`.

<Example id="value-text" />

### Changing the orientation

By default, the progress is assumed to be horizontal. To change the orientation to vertical, set the orientation
property in the machine's context to vertical.

> Don't forget to change the styles of the vertical progress by specifying its height

<Example id="vertical" />

### Using the Root Provider

The `RootProvider` component provides a context for the progress. It accepts the value of the `useProgress` hook. You
can leverage it to access the component state and methods from outside the progress.

<Example id="root-provider" />

> If you're using the `RootProvider` component, you don't need to use the `Root` component.

## API Reference

**Component API Reference**

#### React

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `defaultValue` | `number` | No | The initial value of the progress bar when rendered.
Use when you don't need to control the value of the progress bar. |
| `formatOptions` | `NumberFormatOptions` | No | The options to use for formatting the value. |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{ root: string; track: string; label: string; circle: string }>` | No | The ids of the elements in the progress bar. Useful for composition. |
| `locale` | `string` | No | The locale to use for formatting the value. |
| `max` | `number` | No | The maximum allowed value of the progress bar. |
| `min` | `number` | No | The minimum allowed value of the progress bar. |
| `onValueChange` | `(details: ValueChangeDetails) => void` | No | Callback fired when the value changes. |
| `orientation` | `'horizontal' | 'vertical'` | No | The orientation of the element. |
| `translations` | `IntlTranslations` | No | The localized messages to use. |
| `value` | `number` | No | The controlled value of the progress bar. |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | progress |
| `[data-part]` | root |
| `[data-max]` |  |
| `[data-value]` | The value of the item |
| `[data-state]` |  |
| `[data-orientation]` | The orientation of the progress |


**Circle Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**CircleRange Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**CircleRange Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | progress |
| `[data-part]` | circle-range |
| `[data-state]` |  |


**CircleTrack Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**CircleTrack Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | progress |
| `[data-part]` | circle-track |
| `[data-orientation]` | The orientation of the circletrack |


**Label Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | progress |
| `[data-part]` | label |
| `[data-orientation]` | The orientation of the label |


**Range Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Range Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | progress |
| `[data-part]` | range |
| `[data-orientation]` | The orientation of the range |
| `[data-state]` |  |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseProgressReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Track Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ValueText Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**View Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `state` | `ProgressState` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**View Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | progress |
| `[data-part]` | view |
| `[data-state]` |  |


#### Solid

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `defaultValue` | `number` | No | The initial value of the progress bar when rendered.
Use when you don't need to control the value of the progress bar. |
| `formatOptions` | `NumberFormatOptions` | No | The options to use for formatting the value. |
| `ids` | `Partial<{ root: string; track: string; label: string; circle: string }>` | No | The ids of the elements in the progress bar. Useful for composition. |
| `locale` | `string` | No | The locale to use for formatting the value. |
| `max` | `number` | No | The maximum allowed value of the progress bar. |
| `min` | `number` | No | The minimum allowed value of the progress bar. |
| `onValueChange` | `(details: ValueChangeDetails) => void` | No | Callback fired when the value changes. |
| `orientation` | `'horizontal' | 'vertical'` | No | The orientation of the element. |
| `translations` | `IntlTranslations` | No | The localized messages to use. |
| `value` | `number` | No | The controlled value of the progress bar. |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | progress |
| `[data-part]` | root |
| `[data-max]` |  |
| `[data-value]` | The value of the item |
| `[data-state]` |  |
| `[data-orientation]` | The orientation of the progress |


**Circle Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'svg'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**CircleRange Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'circle'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**CircleRange Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | progress |
| `[data-part]` | circle-range |
| `[data-state]` |  |


**CircleTrack Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'circle'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**CircleTrack Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | progress |
| `[data-part]` | circle-track |
| `[data-orientation]` | The orientation of the circletrack |


**Label Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'label'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | progress |
| `[data-part]` | label |
| `[data-orientation]` | The orientation of the label |


**Range Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Range Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | progress |
| `[data-part]` | range |
| `[data-orientation]` | The orientation of the range |
| `[data-state]` |  |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseProgressReturn` | Yes |  |
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Track Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ValueText Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'span'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**View Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `state` | `ProgressState` | Yes |  |
| `asChild` | `(props: ParentProps<'span'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**View Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | progress |
| `[data-part]` | view |
| `[data-state]` |  |


#### Vue

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `defaultValue` | `number` | No | The initial value of the progress bar when rendered.
Use when you don't need to control the value of the progress bar. |
| `formatOptions` | `NumberFormatOptions` | No | The options to use for formatting the value. |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{ root: string; track: string; label: string; circle: string }>` | No | The ids of the elements in the progress bar. Useful for composition. |
| `locale` | `string` | No | The locale to use for formatting the value. |
| `max` | `number` | No | The maximum allowed value of the progress bar. |
| `min` | `number` | No | The minimum allowed value of the progress bar. |
| `modelValue` | `number` | No | The v-model value of the progress |
| `orientation` | `'horizontal' | 'vertical'` | No | The orientation of the element. |
| `translations` | `IntlTranslations` | No | The localized messages to use. |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | progress |
| `[data-part]` | root |
| `[data-max]` |  |
| `[data-value]` | The value of the item |
| `[data-state]` |  |
| `[data-orientation]` | The orientation of the progress |


**Circle Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**CircleRange Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**CircleRange Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | progress |
| `[data-part]` | circle-range |
| `[data-state]` |  |


**CircleTrack Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**CircleTrack Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | progress |
| `[data-part]` | circle-track |
| `[data-orientation]` | The orientation of the circletrack |


**Label Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | progress |
| `[data-part]` | label |
| `[data-orientation]` | The orientation of the label |


**Range Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Range Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | progress |
| `[data-part]` | range |
| `[data-orientation]` | The orientation of the range |
| `[data-state]` |  |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `ProgressApi<PropTypes>` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Track Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ValueText Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**View Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `state` | `ProgressState` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**View Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | progress |
| `[data-part]` | view |
| `[data-state]` |  |


#### Svelte

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `defaultValue` | `number` | No | The initial value of the progress bar when rendered.
Use when you don't need to control the value of the progress bar. |
| `formatOptions` | `NumberFormatOptions` | No | The options to use for formatting the value. |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{ root: string; track: string; label: string; circle: string }>` | No | The ids of the elements in the progress bar. Useful for composition. |
| `locale` | `string` | No | The locale to use for formatting the value. |
| `max` | `number` | No | The maximum allowed value of the progress bar. |
| `min` | `number` | No | The minimum allowed value of the progress bar. |
| `onValueChange` | `(details: ValueChangeDetails) => void` | No | Callback fired when the value changes. |
| `orientation` | `'horizontal' | 'vertical'` | No | The orientation of the element. |
| `ref` | `Element` | No |  |
| `translations` | `IntlTranslations` | No | The localized messages to use. |
| `value` | `number` | No | The controlled value of the progress bar. |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | progress |
| `[data-part]` | root |
| `[data-max]` |  |
| `[data-value]` | The value of the item |
| `[data-state]` |  |
| `[data-orientation]` | The orientation of the progress |


**Circle Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'svg'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**CircleRange Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'circle'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**CircleRange Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | progress |
| `[data-part]` | circle-range |
| `[data-state]` |  |


**CircleTrack Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'circle'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**CircleTrack Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | progress |
| `[data-part]` | circle-track |
| `[data-orientation]` | The orientation of the circletrack |


**Context Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `api` | `Snippet<[UseProgressContext]>` | No |  |


**Label Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'label'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**Label Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | progress |
| `[data-part]` | label |
| `[data-orientation]` | The orientation of the label |


**Range Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**Range Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | progress |
| `[data-part]` | range |
| `[data-orientation]` | The orientation of the range |
| `[data-state]` |  |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseProgressReturn` | Yes |  |
| `ref` | `Element` | No |  |


**Track Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**ValueText Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'span'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**View Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `state` | `ProgressState` | Yes |  |
| `asChild` | `Snippet<[PropsFn<'span'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**View Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | progress |
| `[data-part]` | view |
| `[data-state]` |  |


## Accessibility

Complies with the [the progressbar role requirements.](https://w3c.github.io/aria/#progressbar).