Progress - Linear

Preview Component

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

No preview available for linear-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.Track>
      <Progress.Range />
    </Progress.Track>
  </Progress.Root>
)

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

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

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'

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

<template>
  <Progress.Root :model-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'

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'

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

<template>
  <Progress.Root :model-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'

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'

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

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

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'

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

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'

const Vertical = () => (
  <Progress.Root orientation="vertical">
    <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'
</script>

<template>
  <Progress.Root orientation="vertical">
    <Progress.Label>Label</Progress.Label>
    <Progress.ValueText />
    <Progress.Track>
      <Progress.Range />
    </Progress.Track>
  </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`