Progress

Progress reports completion of a task, such as uploading a file or loading a page. It is a stateless controlled view: your Model owns a determinate value when one is known, while omitting value renders indeterminate progress. Use Meter instead for a scalar measurement that is not task completion.

Pass value when the amount completed is known. Spread attributes.label onto the visible label, attributes.progress onto the element that carries the progressbar role, and attributes.indicator onto the filled portion. The indicator width reflects the value's position within the range.

import type { HtmlBuilder } from 'foldkit/html'

import { Progress } from '@foldkit/ui'

const view = (h: HtmlBuilder<Message>) =>
  Progress.view(
    {
      id: 'upload',
      value: 42,
      max: 100,
      valueText: '42 percent',
      toView: attributes =>
        h.div(
          [h.Class('flex flex-col gap-2')],
          [
            h.span([...attributes.label], ['Upload']),
            h.div(
              [
                ...attributes.progress,
                h.Class('h-3 w-full rounded-full bg-gray-200'),
              ],
              [
                h.div(
                  [
                    ...attributes.track,
                    h.Class('h-full w-full overflow-hidden'),
                  ],
                  [
                    h.div([
                      ...attributes.indicator,
                      h.Class('h-full rounded-full bg-blue-600'),
                    ]),
                  ],
                ),
              ],
            ),
          ],
        ),
    },
    h,
  )

Omit value when progress cannot yet be quantified. The progressbar then omits aria-valuemin, aria-valuemax, and aria-valuenow. The progress, track, and indicator groups receive data-state="indeterminate" and data-indeterminate so the consumer can provide an appropriate animation.

import type { HtmlBuilder } from 'foldkit/html'

import { Progress } from '@foldkit/ui'

const view = (h: HtmlBuilder<Message>) =>
  Progress.view(
    {
      id: 'loading',
      valueText: 'Loading',
      toView: attributes =>
        h.div(
          [h.Class('flex flex-col gap-2')],
          [
            h.span([...attributes.label], ['Loading']),
            h.div(
              [
                ...attributes.progress,
                h.Class('h-3 w-full rounded-full bg-gray-200 overflow-hidden'),
              ],
              [
                h.div([
                  ...attributes.indicator,
                  h.Class(
                    'h-full w-1/3 rounded-full bg-blue-600 animate-pulse',
                  ),
                ]),
              ],
            ),
          ],
        ),
    },
    h,
  )

Progress is headless. Your toView callback controls its markup and styling.

For determinate progress, indicator carries an inline width matching the value's position within the normalized range. Indeterminate progress leaves the width entirely to consumer styling.

The progressbar receives role="progressbar" and an accessible name. By default, it is named through aria-labelledby, which points to the id carried by the label attribute group. Use ariaLabel when there is no visible label, or ariaLabelledBy to reference a different labeling element. When both overrides are provided, ariaLabel takes precedence.

Determinate progress receives aria-valuemin, aria-valuemax, and aria-valuenow. The value is clamped into [min, max]; if max is lower than min, it is normalized to min before the attributes are emitted. Indeterminate progress omits all three numeric ARIA attributes to communicate that its current value is unknown.

valueText accepts either a string or a (value, max) => string formatter. Strings work for both states. The formatter is evaluated only for determinate progress, because indeterminate progress has no numeric value to format.

Progress is read-only and has no keyboard interaction.

Configuration object passed to Progress.view().

Attribute groups provided to the toView callback.