Progress - Circular

An element that shows either determinate or indeterminate progress.

0%0%

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.Circle>
      <Progress.CircleTrack />
      <Progress.CircleRange />
    </Progress.Circle>
  </Progress.Root>
)

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

export const Basic = () => (
  <Progress.Root>
    <Progress.Label>Label</Progress.Label>
    <Progress.ValueText />
    <Progress.Circle>
      <Progress.CircleTrack />
      <Progress.CircleRange />
    </Progress.Circle>
  </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.Circle>
      <Progress.CircleTrack />
      <Progress.CircleRange />
    </Progress.Circle>
  </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.Circle>
      <Progress.CircleTrack />
      <Progress.CircleRange />
    </Progress.Circle>
  </Progress.Root>
)

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

export const InitialValue = () => (
  <Progress.Root value={70}>
    <Progress.Label>Label</Progress.Label>
    <Progress.ValueText />
    <Progress.Circle>
      <Progress.CircleTrack />
      <Progress.CircleRange />
    </Progress.Circle>
  </Progress.Root>
)

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

<template>
  <Progress.Root :model-value="70">
    <Progress.Label>Label</Progress.Label>
    <Progress.ValueText />
    <Progress.Circle>
      <Progress.CircleTrack />
      <Progress.CircleRange />
    </Progress.Circle>
  </Progress.Root>
</template>

Specifying the 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.Circle>
      <Progress.CircleTrack />
      <Progress.CircleRange />
    </Progress.Circle>
  </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.Circle>
      <Progress.CircleTrack />
      <Progress.CircleRange />
    </Progress.Circle>
  </Progress.Root>
)

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

<template>
  <Progress.Root :model-value="20" :min="10" :max="30">
    <Progress.Label>Label</Progress.Label>
    <Progress.ValueText />
    <Progress.Circle>
      <Progress.CircleTrack />
      <Progress.CircleRange />
    </Progress.Circle>
  </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.Circle>
      <Progress.CircleTrack />
      <Progress.CircleRange />
    </Progress.Circle>
  </Progress.Root>
)

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

export const Indeterminate = () => (
  <Progress.Root value={null}>
    <Progress.Label>Label</Progress.Label>
    <Progress.ValueText />
    <Progress.Circle>
      <Progress.CircleTrack />
      <Progress.CircleRange />
    </Progress.Circle>
  </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.Circle>
      <Progress.CircleTrack />
      <Progress.CircleRange />
    </Progress.Circle>
  </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.Circle>
      <Progress.CircleTrack />
      <Progress.CircleRange />
    </Progress.Circle>
  </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.Circle>
      <Progress.CircleTrack />
      <Progress.CircleRange />
    </Progress.Circle>
  </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.Circle>
      <Progress.CircleTrack />
      <Progress.CircleRange />
    </Progress.Circle>
  </Progress.Root>
</template>

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 RootProvider = () => {
  const progress = useProgress()

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

      <Progress.RootProvider value={progress}>
        <Progress.Label>Label</Progress.Label>
        <Progress.ValueText />
        <Progress.Circle>
          <Progress.CircleTrack />
          <Progress.CircleRange />
        </Progress.Circle>
      </Progress.RootProvider>
    </>
  )
}

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

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

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

      <Progress.RootProvider value={progress}>
        <Progress.Label>Label</Progress.Label>
        <Progress.ValueText />
        <Progress.Circle>
          <Progress.CircleTrack />
          <Progress.CircleRange />
        </Progress.Circle>
      </Progress.RootProvider>
    </>
  )
}

<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.Circle>
      <Progress.CircleTrack />
      <Progress.CircleRange />
    </Progress.Circle>
  </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..