Progress
Displays an indicator showing the completion progress of a task, typically displayed as a progress bar.
Example
Progress(value: 50, class: "w-[60%]", aria: {label: "Progress"})
With label
ProgressLabel names the progress bar (aria-labelledby on the root); ProgressValue shows the formatted value.
Progress(value: 56, class: "w-[60%]") do
ProgressLabel { "Upload progress" }
ProgressValue()
end
Min and max
The bar fills to the percentage of value between min: and max:. aria: {valuetext:} replaces the default text (43%).
Progress(value: 3, max: 7, class: "w-[60%]", aria: {valuetext: "Step 3 of 7"}) do
ProgressLabel { "Onboarding" }
ProgressValue { |_formatted, value| "#{value.to_i} of 7" }
end
Indeterminate
value: nil means the progress is unknown: no aria-valuenow, and every part gets data-indeterminate to style it.
Progress(value: nil, class: "w-[60%]") do
ProgressLabel { "Preparing export" }
end
With custom indicator color
Progress(value: 35, class: "w-[60%] **:data-[slot=progress-indicator]:bg-green-600", aria: {label: "Progress"})
Installation
Using RubyUI CLI
Run the install command
rails g ruby_ui:component Progress
Manual installation
1
Add RubyUI::Progress to app/components/ruby_ui/progress/progress.rb
# frozen_string_literal: true
require "securerandom"
module RubyUI
# A progress bar (role progressbar) mirroring shadcn's Base UI Progress:
# the root holds optional ProgressLabel / ProgressValue children and always
# renders the track and indicator after them.
#
# value: nil makes it indeterminate (no aria-valuenow). min:/max: set the
# range; the indicator width and the default aria-valuetext use the
# percentage of value between them. Pass aria: {valuetext: "..."} to
# replace the text.
class Progress < Base
# data-slot plus the status attribute Base UI puts on every part
# (data-progressing, data-complete or data-indeterminate).
def self.state_data(context, slot)
status = context[:ruby_ui_progress]&.dig(:status)
{data: {slot: slot, **(status ? {status => true} : {})}}
end
def initialize(value: 0, min: 0, max: 100, **attrs)
@min = min.to_f
@max = max.to_f
@raw_value = value
@value = finite(value)&.clamp(*[@min, @max].sort)
# A given aria-valuetext (aria: {valuetext:} or aria_valuetext:)
# replaces the default one; mix would join or duplicate them.
@valuetext = attrs.delete(:aria_valuetext)
aria = attrs[:aria]
if aria.is_a?(Hash) && aria.key?(:valuetext)
@valuetext = aria[:valuetext]
attrs = attrs.merge(aria: aria.except(:valuetext))
end
super(**attrs)
end
# Children are captured first so aria-labelledby only points at a
# ProgressLabel that actually rendered.
def view_template(&block)
previous = context[:ruby_ui_progress]
state = context[:ruby_ui_progress] = {
status: status,
value: @raw_value,
formatted_value: formatted_value,
percentage: percentage,
label_id: "progress-#{SecureRandom.hex(4)}-label"
}
body = block ? capture(&block) : ""
root_attrs = state[:labelledby] ? mix({aria: {labelledby: state[:labelledby]}}, attrs) : attrs
div(**root_attrs) do
raw(safe(body))
ProgressTrack { ProgressIndicator() }
end
ensure
context[:ruby_ui_progress] = previous
end
private
def finite(value)
return nil if value.nil?
number = value.to_f
number.finite? ? number : nil
end
def status
return :indeterminate if @value.nil?
(@value == @max) ? :complete : :progressing
end
def percentage
return nil if @value.nil?
range = @max - @min
return 0.0 unless range.positive?
((@value - @min) / range * 100).clamp(0.0, 100.0)
end
# What Base UI's default Intl percent format gives: "56%".
def formatted_value
percentage ? "#{percentage.round}%" : ""
end
def number(value)
((value % 1).zero? ? value.to_i : value).to_s
end
def default_attrs
{
role: "progressbar",
aria: {
valuemin: number(@min),
valuemax: number(@max),
valuenow: @value && number(@value),
valuetext: @valuetext || (@value ? formatted_value : "indeterminate progress")
},
data: {slot: "progress"}.merge(status => true),
class: "flex flex-wrap gap-3"
}
end
end
end
2
Add RubyUI::ProgressDocs to app/components/ruby_ui/progress/progress_docs.rb
# frozen_string_literal: true
class Views::Docs::Progress < Views::Base
def view_template
component = "Progress"
div(class: "max-w-2xl mx-auto w-full py-10 space-y-10") do
render Docs::Header.new(title: "Progress", description: "Displays an indicator showing the completion progress of a task, typically displayed as a progress bar.")
render Docs::VisualCodeExample.new(title: "Example", context: self) do
<<~RUBY
Progress(value: 50, class: "w-[60%]", aria: {label: "Progress"})
RUBY
end
render Docs::VisualCodeExample.new(title: "With label", description: "ProgressLabel names the progress bar (aria-labelledby on the root); ProgressValue shows the formatted value.", context: self) do
<<~RUBY
Progress(value: 56, class: "w-[60%]") do
ProgressLabel { "Upload progress" }
ProgressValue()
end
RUBY
end
render Docs::VisualCodeExample.new(title: "Min and max", description: "The bar fills to the percentage of value between min: and max:. aria: {valuetext:} replaces the default text (43%).", context: self) do
<<~RUBY
Progress(value: 3, max: 7, class: "w-[60%]", aria: {valuetext: "Step 3 of 7"}) do
ProgressLabel { "Onboarding" }
ProgressValue { |_formatted, value| "\#{value.to_i} of 7" }
end
RUBY
end
render Docs::VisualCodeExample.new(title: "Indeterminate", description: "value: nil means the progress is unknown: no aria-valuenow, and every part gets data-indeterminate to style it.", context: self) do
<<~RUBY
Progress(value: nil, class: "w-[60%]") do
ProgressLabel { "Preparing export" }
end
RUBY
end
render Docs::VisualCodeExample.new(title: "With custom indicator color", context: self) do
<<~RUBY
Progress(value: 35, class: "w-[60%] **:data-[slot=progress-indicator]:bg-green-600", aria: {label: "Progress"})
RUBY
end
render Components::ComponentSetup::Tabs.new(component_name: component)
render Docs::ComponentsTable.new(component_files(component))
end
end
end
3
Add RubyUI::ProgressIndicator to app/components/ruby_ui/progress/progress_indicator.rb
# frozen_string_literal: true
module RubyUI
# The filled part of the track. Its width is the percentage of the value
# between min and max (no width when indeterminate). Progress renders it.
class ProgressIndicator < Base
def view_template
percentage = context[:ruby_ui_progress]&.dig(:percentage)
width = percentage && {style: "inset-inline-start: 0px; height: inherit; width: #{format_percentage(percentage)}%;"}
div(**mix(Progress.state_data(context, "progress-indicator"), width || {}, attrs))
end
private
def default_attrs
{class: "h-full bg-primary transition-all"}
end
def format_percentage(value)
((value % 1).zero? ? value.to_i : value.round(4)).to_s
end
end
end
4
Add RubyUI::ProgressLabel to app/components/ruby_ui/progress/progress_label.rb
# frozen_string_literal: true
require "securerandom"
module RubyUI
# Names the progress bar: inside Progress, the root gets aria-labelledby
# pointing at this element.
class ProgressLabel < Base
def view_template(&)
progress = context[:ruby_ui_progress]
# The root's generated id goes to the first label without an id; any
# other label gets its own, so ids stay unique.
id = attrs[:id] || (progress && !progress[:labelledby] && progress[:label_id]) || "progress-#{SecureRandom.hex(4)}-label"
progress[:labelledby] = id if progress
span(**mix(Progress.state_data(context, "progress-label"), attrs.except(:id), {id: id}), &)
end
private
def default_attrs
{role: "presentation", class: "text-sm font-medium"}
end
end
end
5
Add RubyUI::ProgressTrack to app/components/ruby_ui/progress/progress_track.rb
# frozen_string_literal: true
module RubyUI
# The bar behind the indicator. Progress renders it after its children.
class ProgressTrack < Base
def view_template(&)
div(**mix(Progress.state_data(context, "progress-track"), attrs), &)
end
private
def default_attrs
{class: "relative flex h-1.5 w-full items-center overflow-x-hidden rounded-full bg-muted"}
end
end
end
6
Add RubyUI::ProgressValue to app/components/ruby_ui/progress/progress_value.rb
# frozen_string_literal: true
module RubyUI
# Shows the formatted value ("56%"; empty when indeterminate). Hidden from
# assistive tech: the progressbar already announces it. A block replaces
# the text and receives the formatted value and the value given to
# Progress, before clamping (nil when indeterminate).
class ProgressValue < Base
def view_template(&block)
progress = context[:ruby_ui_progress] || {}
span(**mix(Progress.state_data(context, "progress-value"), attrs)) do
if block
yield(progress[:formatted_value].to_s, progress[:value])
else
plain progress[:formatted_value].to_s
end
end
end
private
def default_attrs
{aria: {hidden: "true"}, class: "ml-auto text-sm text-muted-foreground tabular-nums"}
end
end
end
Components
| Component | Built using | Source |
|---|---|---|
Progress | Phlex | |
ProgressDocs | Phlex | |
ProgressIndicator | Phlex | |
ProgressLabel | Phlex | |
ProgressTrack | Phlex | |
ProgressValue | Phlex |