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
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] | |
[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..