Progress - Circular

Preview Component

Please note, the API of this component is currently in a preview phase and is subject to change.

No preview available for circular-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'

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'

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'
</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'

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'

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'
</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'

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'

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'
</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'

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'

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'
</script>

<template>
  <Progress.Root :value="null">
    <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'

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'

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'
</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>

API Reference

Root

Prop	Type	Default
`asChild`	`boolean`
`defaultValue`	`number`
`dir`	`'ltr' \| 'rtl'`	`"ltr"`
`getRootNode`	`() => Node \| ShadowRoot \| Document`
`id`	`string`
`max`	`number`
`min`	`number`
`orientation`	`Orientation`	`"horizontal"`
`translations`	`IntlTranslations`
`value`	`number`

View

Prop	Type	Default
`state`	`ProgressState`
`asChild`	`boolean`

Label

Prop	Type	Default
`asChild`	`boolean`

Range

Prop	Type	Default
`asChild`	`boolean`

Track

Prop	Type	Default
`asChild`	`boolean`

Circle

Prop	Type	Default
`asChild`	`boolean`

ValueText

Prop	Type	Default
`asChild`	`boolean`

CircleRange

Prop	Type	Default
`asChild`	`boolean`

CircleTrack

Prop	Type	Default
`asChild`	`boolean`