Skip to content

Early previewhamur is not on npm yet. The components are being built in the open, follow along on GitHub.

FeedbackReact

Progress

Displays the status of a task that takes a long time, such as an upload or an export.

Rendered by React 19.3.1

import * as React from 'react'
import { Progress } from '@hamur/react/progress'

export default function ProgressExample() {
  const [value, setValue] = React.useState<number | null>(20)
  return (
    <div className="stack">
      <Progress.Root className="range" value={value}>
        <div className="range-head">
          <Progress.Label>Uploading</Progress.Label>
          <Progress.Value className="muted" />
        </div>
        <Progress.Track className="range-track">
          <Progress.Indicator className="range-fill" />
        </Progress.Track>
      </Progress.Root>
      <div className="row">
        <button
          type="button"
          className="button"
          onClick={() => setValue((current) => Math.min(100, (current ?? 0) + 20))}
        >
          Add 20
        </button>
        <button type="button" className="button" onClick={() => setValue(null)}>
          Indeterminate
        </button>
        <button type="button" className="button" onClick={() => setValue(20)}>
          Reset
        </button>
      </div>
    </div>
  )
}
187Tests passing in React · 0 failing
4.3 KiBSize
Not measured yetMemory
Not measured yetSpeed
productdevbook and 13 upstream authors8 commits · last

Installation

npm i @hamur/react

Not on npm yet. The package goes out under the chosen name.

Anatomy

Import the component and assemble its parts:

<Progress.Root>
  <Progress.Label />
  <Progress.Value />
  <Progress.Track>
    <Progress.Indicator />
  </Progress.Track>
</Progress.Root>

Examples

The demo at the top is the one example this component has so far.

API reference

8 props across 5 parts, in React syntax. className, style, render are listed once, under Shared props.

IndicatorProgress.Indicator

Visualizes the completion status of the task. Renders a <div>.

Indicator data attributes
Data attributeDescription
data-completePresent when the progress has completed.
data-indeterminatePresent when the progress is in indeterminate state.
data-progressingPresent while the progress is progressing.

LabelProgress.Label

An accessible label for the progress bar. Renders a <span>.

Label data attributes
Data attributeDescription
data-completePresent when the progress has completed.
data-indeterminatePresent when the progress is in indeterminate state.
data-progressingPresent while the progress is progressing.

RootProgress.Root

Groups all parts of the progress bar and provides the task completion status to screen readers. Renders a <div>.

Root props
PropTypeDefault
valuerequiredThe current value.number | null—
aria-valuetextA string value that provides a user-friendly name for aria-valuenow, the current value of the progress bar.string—
getAriaValueTextAccepts a function which returns a string value that provides a human-readable text alternative for the current value of the progress bar.((formattedValue: string, value: number | null) => string)—
localeThe locale used by Intl.NumberFormat when formatting the value.Intl.LocalesArgument—
minThe minimum value.number0
maxThe maximum value.number100
formatOptions to format the value.Intl.NumberFormatOptions—
Root data attributes
Data attributeDescription
data-completePresent when the progress has completed.
data-indeterminatePresent when the progress is in indeterminate state.
data-progressingPresent while the progress is progressing.

TrackProgress.Track

Contains the progress bar indicator. Renders a <div>.

Track data attributes
Data attributeDescription
data-completePresent when the progress has completed.
data-indeterminatePresent when the progress is in indeterminate state.
data-progressingPresent while the progress is progressing.

ValueProgress.Value

A text element displaying the current value. Renders a <span>.

Value props
PropTypeDefault
children((formattedValue: string | null, value: number | null) => React.ReactNode) | null—
Value data attributes
Data attributeDescription
data-completePresent when the progress has completed.
data-indeterminatePresent when the progress is in indeterminate state.
data-progressingPresent while the progress is progressing.

Shared props

Every part that renders an element takes these.

Shared props
PropType
classNameCSS class applied to the element, or a function that returns a class based on the component's state.string | ((state: State) => string | undefined)
styleStyle applied to the element, or a function that returns a style object based on the component's state.React.CSSProperties | ((state: State) => React.CSSProperties | undefined)
renderAllows you to replace the component's HTML element with a different tag, or compose it with another component.React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, State>

Keyboard and accessibility

Keyboard

Progress takes no focus and has no keys of its own.

Accessibility

What the parts set
PartSetsSo that
Rootrole="progressbar", aria-valuemin, aria-valuemax, aria-valuenow (left out while the value is unknown)a screen reader reads how far the task is, or that it is in progress
Rootaria-valuetext from format, getAriaValueText or aria-valuetextthe value is read as written, such as "40%"
Rootaria-labelledby to Labelthe bar is read with its name
Valuearia-hidden="true"the visible number is not read twice

Focus order

  1. Progress is not focusable; focus passes over it.