Skip to content
Destyler UI Destyler UI Destyler UI
Docs
Progress

Progress

Linear progress is a simple progress bar that can be used to show the progress of a task such as downloading a file, uploading an image, etc.

Features

Install

Install the component from your command line.

Terminal window 
      
        

          

            npm
             
            install
             
            @destyler/progress @destyler/vue
Terminal window 
      
        

          

            npm
             
            install
             
            @destyler/progress @destyler/react
Terminal window 
      
        

          

            npm
             
            install
             
            @destyler/progress @destyler/svelte
Terminal window 
      
        

          

            npm
             
            install
             
            @destyler/progress @destyler/solid

Anatomy

Import all parts and piece them together.

<script setup lang="ts">
import * as progress from "@destyler/progress"
import { normalizeProps, useMachine } from "@destyler/vue"
import { computed,useId } from "vue"


const [state, send] = useMachine(progress.machine({
  id: useId(),
  value: 30
}))


const api = computed(() =>
  progress.connect(state.value, send, normalizeProps),
)
</script>


<template>
  <div v-bind="api.getRootProps()">
    <div v-bind="api.getLabelProps()"></div>
    <div v-bind="api.getTrackProps()">
      <div v-bind="api.getRangeProps()" />
    </div>
  </div>
</template>
import * as progress from '@destyler/progress'
import { normalizeProps, useMachine } from '@destyler/react'
import { useId } from 'react'


export default function Progress() {
  const [state, send] = useMachine(progress.machine({
    id: useId(),
    value: 30,
  }))


  const api = progress.connect(state, send, normalizeProps)


  return (
    <div {...api.getRootProps()}>
      <div {...api.getLabelProps()}></div>
      <div {...api.getTrackProps()}>
        <div {...api.getRangeProps()}/>
      </div>
    </div>
  )
}
<script lang="ts">
  import * as progress from "@destyler/progress"
  import { normalizeProps, useMachine } from "@destyler/svelte"


  const id = $props.id()


  const [state, send] = useMachine(progress.machine({
    id,
    value: 30
  }))


  const api = $derived(progress.connect(state, send, normalizeProps))
</script>


<div {...api.getRootProps()}>
  <div {...api.getLabelProps()}></div>
  <div {...api.getTrackProps()}>
    <div {...api.getRangeProps()}></div>
  </div>
</div>
import * as progress from '@destyler/progress'
import { normalizeProps, useMachine } from '@destyler/solid'
import { createMemo, createUniqueId } from 'solid-js'


export default function Progress() {
  const [state, send] = useMachine(progress.machine({
    id: createUniqueId(),
    value: 30,
  }))


  const api = createMemo(() => progress.connect(state, send, normalizeProps))


  return (
    <div {...api().getRootProps()}>
      <div {...api().getLabelProps()}></div>
      <div {...api().getTrackProps()}>
        <div {...api().getRangeProps()}/>
      </div>
    </div>
  )
}

Setting the value

use the api.setValue method to set the value of the progress bar.

const [state, send] = useMachine(
  progress.machine({
    value: 50,
  }),
)

Setting the min number and max number values

By default, the progress bar has a min value of 0 and a max value of 100. You can change these values by passing the min and max options to the machine.

const [state, send] = useMachine(
  progress.machine({
    min: 0,
    max: 1000,
  }),
)

Use the indeterminate state

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

Set value to null to indicate an indeterminate value for operations whose progress can’t be determined (e.g., attempting to reconnect to a server).

const [state, send] = useMachine(
  progress.machine({
    value: null,
  }),
)

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 valueText part.

const [state, send] = useMachine(
  progress.machine({
    translations: {
      valueText: ({ value, max }) =>
        value == null ? "Loading..." : `${value} of ${max} items loaded`,
    },
  }),
)

Then you need to render the valueText part in your component.

<script setup lang="ts">
import * as progress from "@destyler/progress"
import { normalizeProps, useMachine } from "@destyler/vue"
import { computed,useId } from "vue"


const [state, send] = useMachine(progress.machine({
  id: useId(),
  value: 30,
  translations: {
    valueText: ({ value, max }) =>
      value == null ? "Loading..." : `${value} of ${max} items loaded`,
  },
}))


const api = computed(() =>
  progress.connect(state.value, send, normalizeProps),
)
</script>


<template>
  <div v-bind="api.getValueTextProps()">
    {{ api.valueAsString }}
  </div>
</template>
import * as progress from '@destyler/progress'
import { normalizeProps, useMachine } from '@destyler/react'
import { useId } from 'react'


export default function Progress() {
  const [state, send] = useMachine(progress.machine({
    id: useId(),
    value: 30,
    translations: {
      valueText: ({ value, max }) =>
        value == null ? "Loading..." : `${value} of ${max} items loaded`,
    },
  }))


  const api = progress.connect(state, send, normalizeProps)


  return (
    <div {...api.getValueTextProps()}>
      {api.valueAsString}
    </div>
  )
}
<script lang="ts">
  import * as progress from "@destyler/progress"
  import { normalizeProps, useMachine } from "@destyler/svelte"


  const id = $props.id()


  const [state, send] = useMachine(progress.machine({
    id,
    value: 30,
    translations: {
      valueText: ({ value, max }) =>
        value == null ? "Loading..." : `${value} of ${max} items loaded`,
    },
  }))


  const api = $derived(progress.connect(state, send, normalizeProps))
</script>


<div {...api.getValueTextProps()}>
  {api.valueAsString}
</div>
import * as progress from '@destyler/progress'
import { normalizeProps, useMachine } from '@destyler/solid'
import { createMemo, createUniqueId } from 'solid-js'


export default function Progress() {
  const [state, send] = useMachine(progress.machine({
    id: createUniqueId(),
    value: 30,
    translations: {
      valueText: ({ value, max }) =>
        value == null ? "Loading..." : `${value} of ${max} items loaded`,
    },
  }))


  const api = createMemo(() => progress.connect(state, send, normalizeProps))


  return (
    <div {...api().getValueTextProps()}>
      {api().valueAsString}
    </div>
  )
}

Styling Guide

Earlier, we mentioned that each collapse part has a data-part attribute added to them to select and style them in the DOM.

[data-scope="progress"][data-part="root"] {
  /* Styles for the root part */
}


[data-scope="progress"][data-part="track"] {
  /* Styles for the track part */
}


[data-scope="progress"][data-part="range"] {
  /* Styles for the range part */
}

Indeterminate state

To style the indeterminate state, you can use the [data-state=indeterminate] selector.

[data-scope="progress"][data-part="root"][data-state="indeterminate"] {
  /* Styles for the root indeterminate state */
}


[data-scope="progress"][data-part="track"][data-state="indeterminate"] {
  /* Styles for the root indeterminate state */
}


[data-scope="progress"][data-part="range"][data-state="indeterminate"] {
  /* Styles for the root indeterminate state */
}

Methods and Properties

Machine Context

The progress machine exposes the following context properties:

ids
Partial<{ root: string; track: string; label: string; circle: string; }>
The ids of the elements in the progress bar. Useful for composition.
value
number
The current value of the progress bar.
min
number
The minimum allowed value of the progress bar.
max
number
The maximum allowed value of the progress bar.
translations
IntlTranslations
The localized messages to use.
onValueChange
(details: ValueChangeDetails) => void
Callback fired when the value changes.
dir
"ltr" | "rtl"
The document's text/writing direction.
id
string
The unique identifier of the machine.
getRootNode
() => ShadowRoot | Node | Document
A root node to correctly resolve document in custom environments. E.x.: Iframes, Electron.
orientation
Orientation
The orientation of the element.

Machine API

The progress api exposes the following methods:

value
number
The current value of the progress bar.
valueAsString
string
The current value of the progress bar as a string.
setValue
(value: number) => void
Sets the current value of the progress bar.
setToMax
() => void
Sets the current value of the progress bar to the max value.
setToMin
() => void
Sets the current value of the progress bar to the min value.
percent
number
The percentage of the progress bar's value.
percentAsString
string
The percentage of the progress bar's value as a string.
min
number
The minimum allowed value of the progress bar.
max
number
The maximum allowed value of the progress bar.
indeterminate
boolean
Whether the progress bar is indeterminate.

Data Attributes

Root

name
desc
data-scope
progress
data-part
root
data-value
The value of the item
data-orientation
The orientation of the progress

Label

name
desc
data-scope
progress
data-part
label
data-orientation
The orientation of the label

Range

name
desc
data-scope
progress
data-part
range
data-orientation
The orientation of the range

Circle Track

name
desc
data-scope
progress
data-part
circle-track
data-orientation
The orientation of the circletrack

Circle Range

name
desc
data-scope
progress
data-part
circle-range

View

name
desc
data-scope
progress
data-part
view

Popover

Separator