Progress
A determinate progress bar toward task completion.
Installation
Included in poetry-ui — available as
poetry_progress
the moment you've installed Poetry,
with no per-component step. To own the source and edit it, copy it into your app:
bin/rails g poetry:add progress
Default
Open Default standalone
Uploading photos60%
<%= poetry_progress(value: 60, label: "Uploading photos", class: "w-80") %>
Complete
Open Complete standalone
Backup100%
<%= poetry_progress(value: 100, label: "Backup", class: "w-80") %>
Controlled
Open Controlled standalone
Progress50%
<%# Upstream progress-controlled, the Rails way: the Slider drives the
bar live - in an app this is your state (a Turbo Stream morph, a
form value); here the demo-progress controller forwards the
slider's input event. Demo plumbing, not poetry API. %>
<div data-controller="demo-progress" class="flex w-full max-w-sm flex-col gap-4">
<%= poetry_progress(value: 50, label: "Progress", class: "w-full",
"data-demo-progress-target": "progress") %>
<div data-action="poetry:slider:change->demo-progress#update">
<%= poetry_slider(name: "progress_value", value: 50, min: 0, max: 100, step: 1,
label: "Set progress") %>
</div>
</div>
Custom max without value
Open Custom max without value standalone
Steps completed
<%# max: rescales the bar (here 3 of 8 steps); show_value: false hides
the percent readout while keeping the label and aria-value* intact. %>
<div class="w-80">
<%= poetry_progress(value: 3, max: 8, label: "Steps completed", show_value: false) %>
</div>
Label
Open Label standalone
Upload progress56%
<%# Upstream progress-label: the visible caption + the percent readout
(label: is required in poetry - the accessible name - and the
readout renders by default). %>
<%= poetry_progress(value: 56, label: "Upload progress", class: "w-full max-w-sm") %>
API
Poetry::Ui::Progress::Component — options are
constructor keywords (the poetry_* helper forwards them);
slots are composed inside the block. Generated from the gem's source documentation.
| Option | Type | Details | Description |
|---|---|---|---|
| label: | String | required | The progressbar's accessible name and visible caption. |
| max: | Integer | defaults to 100 |
The completion value. |
| show_value: | Boolean | defaults to true |
Set false to hide the percent readout. |
| value: | Integer | required | The current progress, clamped into 0..max:. |
Styling
Every part carries a stable data-slot attribute — target
[data-slot=…] from your own CSS to restyle it. State rides
data attributes on the parts below. This contract is verified against rendered DOM in CI.
| Part | Description |
|---|---|
| [data-slot=progress] | Root (role=progressbar, aria-value* and the accessible name) - label, value readout, and track stack here |
| [data-slot=progress-label] | The visible caption span (label:) |
| [data-slot=progress-value] | The tabular percent readout - renders unless show_value: false |
| [data-slot=progress-track] | The full-width rail the indicator fills |
| [data-slot=progress-indicator] | The filled bar - sized by an inline width percentage computed from value:/max: |