Skip to content
Bladewell

<x-widget.progress>

Progress Blade component for Laravel and Livewire

Progress bars, rings and stacked usage bars. Values in your own units, indeterminate and striped states, and progress.set() to update one from JavaScript. For step-by-step flows, see the stepper. Works inside Livewire components, wire:poll included.

php artisan bladewell:add progress
Also adds
Nothing else. It stands alone.
Works with
Laravel 12 and 13, Livewire 3 and 4, Tailwind CSS 4.1+, PHP 8.3+
Guides
Using Blade components in Livewire 3 and 4 · Livewire file upload with progress and drag and drop

Usage

In scripts

window.progress is available once the progress script has loaded. <x-widget.progress id="upload" label="Uploading" show-label />

JavaScript
progress.set('upload', 60);

// Value out of the bar's max, with your own wording (also what screen readers hear).
// <x-widget.progress id="files" :max="5" label="Files" show-label />
progress.set('files', 3, { text: '3 of 5 files' });

// e.g. from an upload's progress event
request.upload.addEventListener('progress', (event) => {
    progress.set('upload', (event.loaded / event.total) * 100);
});

Livewire

In a Livewire component, pass the value from a property and every render redraws the bar: after an action, or on wire:poll while a job runs. A bar you drive from JavaScript with progress.set() instead, such as from Livewire's upload progress events, goes in a wire:ignore, or the next render puts back the server's value.

Blade
<div wire:poll.1s="refreshExport" class="space-y-6">
    <x-widget.progress :value="$export->processed" :max="$export->total" label="Exporting" show-label :value-text="$export->processed.' of '.$export->total.' rows'" />
</div>

<div x-on:livewire-upload-progress="progress.set('upload', $event.detail.progress)" class="space-y-3">
    <x-widget.file-upload label="Video" wire:model="video" />
    <div wire:ignore>
        <x-widget.progress id="upload" label="Uploading" show-label />
    </div>
</div>

Examples

Linear

Uploading documents 35%
Verification 100%
Withdrawal failed 60%
Paused 40%
Show code
Blade
<div class="grid gap-5 sm:grid-cols-2">
    <x-widget.progress :value="35" label="Uploading documents" show-label />
    <x-widget.progress :value="100" label="Verification" show-label />
    <x-widget.progress :value="60" label="Withdrawal failed" show-label failed />
    <x-widget.progress :value="40" label="Paused" show-label disabled />
</div>

Values

:max makes progress "value out of max" in your own units, and value-text says it in words: shown instead of the percentage and read out by screen readers. label-position puts the label above, beside or inside the bar.

Uploading 3 of 5 files
Storage
1.2 GB of 5 GB
Raised $750 of $1,000
Show code
Blade
<div class="flex w-full flex-col gap-5">
    <x-widget.progress :value="3" :max="5" value-text="3 of 5 files" label="Uploading" show-label />
    <x-widget.progress :value="1.2" :max="5" value-text="1.2 GB of 5 GB" label="Storage" show-label label-position="beside" />
    <x-widget.progress :value="750" :max="1000" value-text="$750 of $1,000" label="Raised" show-label label-position="inside" />
</div>

Indeterminate

indeterminate slides while the amount isn't known yet; striped adds moving stripes to a bar that is. Both stop moving for people who prefer reduced motion.

Preparing your export
Processing payments 65%
Show code
Blade
<div class="grid w-full gap-5 sm:grid-cols-2">
    <x-widget.progress indeterminate label="Preparing your export" show-label />
    <x-widget.progress :value="65" striped label="Processing payments" show-label />
</div>

Live

progress.set() moves the bar and updates what screen readers hear in one call; the script beside this calls it as the import goes. An indeterminate bar turns into a normal one on the first set().

Uploading report.pdf
Importing
0 of 5 files
Show code
Blade
<div class="flex w-full flex-col gap-5">
    <x-widget.progress id="upload-progress" indeterminate label="Uploading report.pdf" show-label />
    <x-widget.progress id="file-progress" :max="5" value-text="0 of 5 files" label="Importing" show-label label-position="beside" />

    <div>
        <button
            type="button"
            class="bg-primary-fill text-on-primary hover:bg-primary-hover focus-visible:ring-primary rounded-xl px-4 py-2.5 text-sm font-medium outline-none focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:ring-offset-surface"
            data-start-import
        >Start</button>
    </div>
</div>
JavaScript, in your own JS file
// Stands in for a real import: five steps, one every 600ms.
document.addEventListener('click', (event) => {
    if (!event.target.closest('[data-start-import]')) {
        return;
    }
    let done = 0;
    const timer = setInterval(() => {
        done++;
        progress.set('upload-progress', done * 20);
        progress.set('file-progress', done, { text: `${done} of 5 files` });
        if (done === 5) {
            clearInterval(timer);
        }
    }, 600);
});

Circular

indeterminate spins for work with no known end.

Uploading
Verified
Failed
Loading
Large
Show code
Blade
<div class="flex flex-wrap items-end gap-8">
    <x-widget.progress.circular :value="35" label="Uploading" show-label />
    <x-widget.progress.circular :value="100" label="Verified" show-label />
    <x-widget.progress.circular :value="60" label="Failed" show-label failed />
    <x-widget.progress.circular indeterminate label="Loading" show-label />
    <x-widget.progress.circular :value="85" size="lg" label="Large" show-label />
</div>

Stacked

Parts of one whole in a single bar with a legend, e.g. storage or a budget. Colours follow the theme in order unless a segment names one; what's left over shows as free.

Storage 37.5 GB of 50 GB used
Show code
Blade
<x-widget.progress.stacked
    class="w-full"
    label="Storage"
    summary="37.5 GB of 50 GB used"
    :max="50"
    :segments="[
        ['label' => 'Photos', 'value' => 18.4, 'text' => '18.4 GB'],
        ['label' => 'Videos', 'value' => 12.1, 'text' => '12.1 GB'],
        ['label' => 'Documents', 'value' => 5, 'text' => '5 GB'],
        ['label' => 'Other', 'value' => 2, 'text' => '2 GB', 'color' => 'muted'],
    ]"
/>

Props

Other attributes, such as autocomplete or data-*, are passed through to the element. class styles the component's outer wrapper.

<x-widget.progress>

Prop Default Description
value 0 How far along it is, out of max. Reaching max turns it green.
max 100 Progress is value out of max: :value="3" :max="5" for files, bytes, money, anything countable.
label null Its name for screen readers ("Progress" if left out); shown too with show-label.
show-label false Shows the label and the value next to the bar, placed by label-position. Without it only screen readers get them (label-position="inside" still shows the value).
label-position 'above' Where the label and value go: above the bar, beside it on one line, or inside a thicker bar.
value-text null Shown instead of the percentage, and read out by screen readers: "3 of 5 files", "1.2 GB of 5 GB".
failed false Turns it red, e.g. for an upload that stopped, and screen readers hear "failed".
disabled false Greyed out, e.g. for a paused job, and screen readers hear "disabled".
size 'md' How thick the bar is: sm, md or lg. label-position="inside" always uses a thicker bar.
indeterminate false The amount isn't known yet: a sliding bar and no value. (A prop, not :value="null": Blade turns a passed null back into the default.)
striped false Moving diagonal stripes on the filled part, to show work is going on. They stay still for people who prefer reduced motion.

<x-widget.progress.circular>

Prop Default Description
value 0 How far along it is, out of max. Reaching max turns it green.
max 100 Progress is value out of max: :value="3" :max="5" for files, bytes, money, anything countable.
label null Its name for screen readers ("Progress" if left out); shown too with show-label.
show-label false Shows the label under the circle.
show-value true The percentage in the centre of the circle.
value-text null Read out by screen readers and shown under the label, e.g. "3 of 5 files". The centre keeps the percentage.
failed false Turns it red, e.g. for an upload that stopped, and screen readers hear "failed".
disabled false Greyed out, e.g. for a paused job, and screen readers hear "disabled".
size 'md' How big the circle is: sm, md or lg.
indeterminate false The amount isn't known yet: a spinning arc and no value. (A prop, not :value="null": Blade turns a passed null back into the default.)

<x-widget.progress.stacked>

Prop Default Description
segments [] Parts of one whole: [['label' => 'Photos', 'value' => 18.4, 'text' => '18.4 GB'], …]. text is optional; color is optional too (primary, link, warning, error, muted) and otherwise follows that order.
max 100 The whole the parts are measured against, e.g. 50 for a 50 GB plan. What's left over shows as free space.
label 'Usage' The heading above the bar, and its name for screen readers.
summary null A summary beside the label, e.g. "37.5 GB of 50 GB used".
legend true Lists each part's colour, name and amount under the bar; false leaves it out.
rest 'Free' Legend name for the space left over; null leaves it out.

Accessibility

All 6 examples above are checked with axe-core against the WCAG 2.2 A and AA rules, in the light theme and the dark one, both as the page draws and with each popover, dialog, toast and tooltip opened, on every change. A change that fails can't be merged. Where axe can't decide, such as contrast on SVG text, the test measures the colours itself instead of letting it pass.

Automated checks can't judge everything: how it sounds in a screen reader, and how it feels to use from the keyboard, still need a person. Check those on your own pages too.

Source

What bladewell:add progress writes to your app with the default namespaces. Prefer to copy by hand? Take these files, plus the ones from the components it also adds , and the theme and base CSS.

resources/views/components/widget/progress/circular.blade.php Show
circular.blade.php
resources/views/components/widget/progress/index.blade.php Show
index.blade.php
resources/views/components/widget/progress/stacked.blade.php Show
stacked.blade.php
resources/js/widget/progress/index.js Show
index.js