Progress

A horizontal progress bar for displaying completion percentage (determinate) or indicating ongoing work without a known total (indeterminate).

Basic Usage

Determinate (known value)

<x-wirekit::progress :value="42" :max="100" label="Upload Progress" />

Indeterminate (unknown duration)

Omit value to render an animated sliding bar for tasks with unknown duration.

<x-wirekit::progress label="Processing…" />

Show Numeric Value

<x-wirekit::progress :value="2145" :max="5000" label="Storage" show-value />

Renders: 2145 / 5000 next to the label.

Variants

The fill color signals semantic meaning:

<x-wirekit::progress :value="75" intent="primary" label="Accent — default" />

<x-wirekit::progress :value="100" intent="success" label="Success — task complete" />

<x-wirekit::progress :value="60" intent="warning" label="Warning — approaching limit" />

<x-wirekit::progress :value="95" intent="danger" label="Danger — quota full" />

Sizes

<x-wirekit::progress :value="50" size="sm" label="Small (h-1)" />

<x-wirekit::progress :value="50" size="md" label="Medium (h-2) — default" />

<x-wirekit::progress :value="50" size="lg" label="Large (h-3)" />

Radial (circular) progress

For a radial progress indicator — the ring shape for dashboards, stat tiles and compact metrics — use the dedicated Radial Progress component. It is the canonical radial progress in WireKit: size and intent options, threshold coloring that turns the ring warning/danger past a limit, and a required accessible name.

Livewire Integration

Pass a reactive value — the bar animates smoothly on updates:

<x-wirekit::progress :value="$this->uploadPercent" label="Uploading file" show-value />

public int $uploadPercent = 0;

public function processChunk()
{
    $this->uploadPercent = min(100, $this->uploadPercent + 10);
}

Width & Layout

The progress bar fills its parent width. Control the width with Tailwind classes directly on the component:

<x-wirekit::progress class="max-w-sm" :value="65" label="Upload" />

Height is controlled by the size prop (sm, md, lg).

Intent

intent is the canonical color axis (matching badge, button, and alert). variant keeps working as a back-compat alias; when both are present, intent wins.

<x-wirekit::stack gap="md">
    <x-wirekit::progress :value="80" intent="success" label="Storage" show-value />
    <x-wirekit::progress :value="55" intent="warning" label="Quota" show-value />
    <x-wirekit::progress :value="20" intent="neutral" label="Draft" show-value />
</x-wirekit::stack>

Animated fill

animation adds optional motion to a determinate fill — the "work in flight" affordance for uploads and streaming. stripes is the barber-pole; shimmer is a single light sweep. Both are purely additive: the bar's value is unchanged, and the motion is disabled under prefers-reduced-motion (stripes freeze but stay visible; the shimmer sweep is removed).

<x-wirekit::progress :value="42" animation="stripes" label="Uploading archive.zip" show-value />

<x-wirekit::progress :value="68" intent="accent" animation="shimmer" label="Downloading update" show-value />

Reduced Motion

WireKit disables all progress and skeleton animations when the user's OS has prefers-reduced-motion: reduce set. This is handled centrally in dist/wirekit.css — no extra configuration needed.

Client-side values

value is a PHP prop, evaluated when the page renders. An upload percentage does not exist then — it arrives later, in Alpine state that Livewire events advance. Binding to the rendered element does not close that: x-bind:value sets a value attribute on a <div>, and nothing reads it, so the bar stays indeterminate, show-value prints nothing, and there is no aria-valuenow at all.

value-expression takes the name of a property in the surrounding Alpine scope and lets the component drive the bar, the readout and aria-valuenow from it:

<div x-data="{ percent: 42 }" class="w-full">
    <x-wirekit::progress value-expression="percent" max="100" label="Uploading" show-value animation="stripes" />
</div>

Pass a property name, not an expression: value-expression="percent" rather than value-expression="percent * 2". The component resolves it through Alpine's scope chain, so it reads the state you already have without you wiring anything to the inner elements.

No value yet is not zero. While the property is null, absent, empty or unparseable, the bar stays indeterminate and aria-valuenow is absent — a bar drawn at 0% would claim that no work has been done, which is a different statement from not knowing yet. An explicit 0 is a real value and renders as one.

Props

Accessibility

• role="progressbar" on the track — the WAI-ARIA progressbar role
• Determinate: sets aria-valuenow, aria-valuemin="0", aria-valuemax="{max}" — screen readers announce the current percentage
• Indeterminate: aria-valuenow is omitted (WAI-ARIA spec for unknown progress)
• aria-labelledby links the bar to its visible label when label is set, so the label is part of the accessible name
• Pass an id when the bar lives in a polling region. The link between label and bar needs an id, and with no id of your own one is generated. That is fine for a bar rendered once — but a wire:poll region re-renders, and a generated id changes with it, so the accessible name is re-resolved on every poll. An id you supply stays put across renders.
• The indeterminate animation respects prefers-reduced-motion: users with reduced-motion settings see a static filled region instead of a sliding bar

Keyboard Interaction

This component is purely presentational and does not respond to keyboard input.

Pitfalls

• Don't omit aria-label if the progress is not visually labeled. A bare <x-wirekit::progress> carries role="progressbar" but screen readers need either a sibling <x-wirekit::label> or an explicit aria-label.

Design Tokens

Customization

Override defaults without publishing views via config/wirekit.php:

'components' => [
    'progress' => [
        'variant' => 'success',
        'size' => 'sm',
    ],
],

Usage & Conventions

Prop conventions — this component uses one or more of the shared semantic prop names (intent / variant / tone / surface). See Prop naming conventions for the canonical vocabulary, alias matrix, and decision tree.

Further Reading

• WAI-ARIA Authoring Practices — Meter / Progress
• MDN: aria-valuenow
• MDN: prefers-reduced-motion