<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 />
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.
<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
Show code Hide code
<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.
Show code Hide code
<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.
Show code Hide code
<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().
Show code Hide code
<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>
// 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.
Show code Hide code
<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.
Show code Hide code
<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
resources/views/components/widget/progress/index.blade.php Show
resources/views/components/widget/progress/stacked.blade.php Show
resources/js/widget/progress/index.js Show