Progress - Linear

An element that shows either determinate or indeterminate progress.

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.

Examples

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

import { Progress } from '@ark-ui/react/progress'

export const Basic = () => (
  <Progress.Root>
    <Progress.Label>Label</Progress.Label>
    <Progress.ValueText />
    <Progress.Track>
      <Progress.Range />
    </Progress.Track>
  </Progress.Root>
)

import { Progress } from '@ark-ui/solid/progress'

export const Basic = () => (
  <Progress.Root>
    <Progress.Label>Label</Progress.Label>
    <Progress.ValueText />
    <Progress.Track>
      <Progress.Range />
    </Progress.Track>
  </Progress.Root>
)

<script setup lang="ts">
import { Progress } from '@ark-ui/vue/progress'
</script>

<template>
  <Progress.Root>
    <Progress.Label>Label</Progress.Label>
    <Progress.ValueText />
    <Progress.Track>
      <Progress.Range />
    </Progress.Track>
  </Progress.Root>
</template>

Setting the initial value

To set the progress's initial value, set the defaultValue prop to a number.

import { Progress } from '@ark-ui/react/progress'

export const InitialValue = () => (
  <Progress.Root defaultValue={70}>
    <Progress.Label>Label</Progress.Label>
    <Progress.ValueText />
    <Progress.Track>
      <Progress.Range />
    </Progress.Track>
  </Progress.Root>
)

import { Progress } from '@ark-ui/solid/progress'

export const InitialValue = () => (
  <Progress.Root value={70}>
    <Progress.Label>Label</Progress.Label>
    <Progress.ValueText />
    <Progress.Track>
      <Progress.Range />
    </Progress.Track>
  </Progress.Root>
)

<script setup lang="ts">
import { Progress } from '@ark-ui/vue/progress'
</script>

<template>
  <Progress.Root :value="70">
    <Progress.Label>Label</Progress.Label>
    <Progress.ValueText />
    <Progress.Track>
      <Progress.Range />
    </Progress.Track>
  </Progress.Root>
</template>

Specifying the minimum and maximum

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:

import { Progress } from '@ark-ui/react/progress'

export const MinMax = () => (
  <Progress.Root defaultValue={20} min={10} max={30}>
    <Progress.Label>Label</Progress.Label>
    <Progress.ValueText />
    <Progress.Track>
      <Progress.Range />
    </Progress.Track>
  </Progress.Root>
)

import { Progress } from '@ark-ui/solid/progress'

export const MinMax = () => (
  <Progress.Root value={20} min={10} max={30}>
    <Progress.Label>Label</Progress.Label>
    <Progress.ValueText />
    <Progress.Track>
      <Progress.Range />
    </Progress.Track>
  </Progress.Root>
)

<script setup lang="ts">
import { Progress } from '@ark-ui/vue/progress'
</script>

<template>
  <Progress.Root :value="20" :min="10" :max="30">
    <Progress.Label>Label</Progress.Label>
    <Progress.ValueText />
    <Progress.Track>
      <Progress.Range />
    </Progress.Track>
  </Progress.Root>
</template>

Using the indeterminate state

The progress component is determinate by default, with the value and max set to 50 and 100 respectively.

Set the state to indeterminate in Progress.Indicator:

import { Progress } from '@ark-ui/react/progress'

export const Indeterminate = () => (
  <Progress.Root value={null}>
    <Progress.Label>Label</Progress.Label>
    <Progress.ValueText />
    <Progress.Track>
      <Progress.Range />
    </Progress.Track>
  </Progress.Root>
)

import { Progress } from '@ark-ui/solid/progress'

export const Indeterminate = () => (
  <Progress.Root value={null}>
    <Progress.Label>Label</Progress.Label>
    <Progress.ValueText />
    <Progress.Track>
      <Progress.Range />
    </Progress.Track>
  </Progress.Root>
)

<script setup lang="ts">
import { Progress } from '@ark-ui/vue/progress'
</script>

<template>
  <Progress.Root>
    <Progress.Label>Label</Progress.Label>
    <Progress.ValueText />
    <Progress.Track>
      <Progress.Range />
    </Progress.Track>
  </Progress.Root>
</template>

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.

import { Progress } from '@ark-ui/react/progress'

export const ValueText = () => (
  <Progress.Root
    translations={{
      value({ value, max }) {
        if (value === null) return 'Loading...'
        return `${value} of ${max} items loaded`
      },
    }}
  >
    <Progress.Label>Label</Progress.Label>
    <Progress.ValueText />
    <Progress.Track>
      <Progress.Range />
    </Progress.Track>
  </Progress.Root>
)

import { Progress } from '@ark-ui/solid/progress'

export const ValueText = () => (
  <Progress.Root
    translations={{
      value({ value, max }) {
        if (value === null) return 'Loading...'
        return `${value} of ${max} items loaded`
      },
    }}
  >
    <Progress.Label>Label</Progress.Label>
    <Progress.ValueText />
    <Progress.Track>
      <Progress.Range />
    </Progress.Track>
  </Progress.Root>
)

<script setup lang="ts">
import { Progress } from '@ark-ui/vue/progress'
</script>

<template>
  <Progress.Root
    :translations="{
      value: ({ value, max }) => (value == null ? 'Loading...' : `${value} of ${max} items loaded`),
    }"
  >
    <Progress.Label>Label</Progress.Label>
    <Progress.ValueText />
    <Progress.Track>
      <Progress.Range />
    </Progress.Track>
  </Progress.Root>
</template>

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

import { Progress } from '@ark-ui/react/progress'

export const Vertical = () => (
  <Progress.Root orientation="vertical">
    <Progress.Label>Label</Progress.Label>
    <Progress.ValueText />
    <Progress.Track>
      <Progress.Range />
    </Progress.Track>
  </Progress.Root>
)

import { Progress } from '@ark-ui/solid/progress'

export const Vertical = () => (
  <Progress.Root orientation="vertical">
    <Progress.Label>Label</Progress.Label>
    <Progress.ValueText />
    <Progress.Track>
      <Progress.Range />
    </Progress.Track>
  </Progress.Root>
)

Example not found

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.

import { Progress, useProgress } from '@ark-ui/react/progress'

export const Basic = () => {
  const progress = useProgress()

  return (
    <>
      <button onClick={() => progress.setToMax()}>Set to MAX</button>

      <Progress.Root>
        <Progress.Label>Label</Progress.Label>
        <Progress.ValueText />
        <Progress.Track>
          <Progress.Range />
        </Progress.Track>
      </Progress.Root>
    </>
  )
}

import { Progress, useProgress } from '@ark-ui/solid/progress'

export const Basic = () => {
  const progress = useProgress()

  return (
    <>
      <button onClick={() => progress().setToMax()}>Set to MAX</button>

      <Progress.Root>
        <Progress.Label>Label</Progress.Label>
        <Progress.ValueText />
        <Progress.Track>
          <Progress.Range />
        </Progress.Track>
      </Progress.Root>
    </>
  )
}

<script setup lang="ts">
import { Progress, useProgress } from '@ark-ui/vue/progress'

const progress = useProgress()
</script>

<template>
  <button @click="progress.setToMax()">Set to MAX</button>

  <Progress.Root>
    <Progress.Label>Label</Progress.Label>
    <Progress.ValueText />
    <Progress.Track>
      <Progress.Range />
    </Progress.Track>
  </Progress.Root>
</template>

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

API Reference

Root

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`id`		`string` The unique identifier of the machine.
`ids`		`Partial<{ root: string; track: string; label: string; circle: string }>` The ids of the elements in the progress bar. Useful for composition.
`max`	`100`	`number` The maximum allowed value of the progress bar.
`min`	`0`	`number` The minimum allowed value of the progress bar.
`orientation`	`'horizontal'`	`Orientation` The orientation of the element.
`translations`		`IntlTranslations` The localized messages to use.
`value`	`50`	`number` The current value of the progress bar.

Data 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

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

CircleRange

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

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

CircleTrack

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

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

Label

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

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

Range

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

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

RootProvider

Prop	Default	Type
`value`		`MachineApi<PropTypes>`
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Track

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

ValueText

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

View

Prop	Default	Type
`state`		`ProgressState`
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

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

Accessibility

Complies with the the progressbar role requirements..