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" variant="accent" label="Accent — default" />

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

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

<x-wirekit::progress :value="95" variant="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.

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