Headless Progress

New version v0.0.9 🚀

An unstyled, fully accessible progress bar for Phoenix LiveView, determinate and indeterminate states, paired-presence data attributes, and a CSS variable driven fill built in. You bring the styling.

Installation:

mix mishka.ui.gen.headless progress

Source: View Source

Package: Mishka Chelekom

Tags:

Headless Base UI Accessible

Overview of the Phoenix and LiveView Headless Progress Component

The Mishka Chelekom Headless Progress ships zero opinionated styling - only the semantic markup, full WAI-ARIA progressbar wiring, and paired-presence state (data-indeterminate/data-progressing/data-complete). Pass value as nil for an indeterminate (loading) bar - aria-valuenow is then omitted and no fill ratio is set. Every part - label, value, track and indicator - is addressable through a *_class attribute, and the indicator exposes a --chelekom-progress CSS variable for the fill ratio, so you style it entirely with your own Tailwind classes while the accessibility keeps working underneath.

**Headless = bring your own design.** The example below is a faithful port of Base UI's own Progress demo. Copy it, then swap the classes for your design system - the behavior never changes.

Base UI Progress example (Phoenix headless)

Export data 20%

<.progress
  id="chelekom-headless-progress-hero"
  value={20}
  label="Export data"
  show_value
  class="grid max-w-full w-60 grid-cols-2 gap-y-2"
  label_class="text-sm font-normal text-neutral-950 dark:text-white"
  value_class="text-right text-sm text-neutral-950 dark:text-white"
  track_class="col-span-2 h-1 overflow-hidden bg-neutral-200 dark:bg-neutral-800"
  indicator_class="bg-neutral-950 transition-[width] duration-500 dark:bg-white"
/>

Parts & data attributes

Each part carries a structural chelekom-progress__* class you can target, plus the shared paired-presence status - exactly one of data-indeterminate, data-progressing or data-complete is present on the root and every part at any time.

Part	data-part	State / ARIA	Purpose
Root	(root)	role="progressbar", aria-valuemin, aria-valuemax, aria-valuenow, aria-valuetext, aria-labelledby	The container for the whole progress bar.
Label	label	Referenced by aria-labelledby	Accessible name, rendered when the label attribute is set.
Value	value	data-indeterminate, data-progressing, data-complete	Optional readout, rendered when show_value is set.
Track	track	data-indeterminate, data-progressing, data-complete	The background rail behind the indicator.
Indicator	indicator	data-indeterminate, data-progressing, data-complete, --chelekom-progress	The filled portion; carries the 0..1 fill ratio as a CSS variable.

Accessibility

Follows the WAI-ARIA Progressbar pattern : the root carries role="progressbar" with aria-valuemin, aria-valuemax, a clamped aria-valuenow and a human aria-valuetext. There is no keyboard interaction - progress bars are not focusable or operable, only announced by assistive technology.

Headless Progress component props

Name	Type	Required	Description
id	string	No	Optional id; anchors aria-labelledby to the label part.
value	integer	No	Current value in min..max; nil renders an indeterminate bar.
min	integer	No	Lower bound of the range. Defaults to 0.
max	integer	No	Upper bound of the range. Defaults to 100.
label	string	No	Accessible label, rendered and wired to aria-labelledby.
value_text	string	No	Human value for aria-valuetext and the readout; defaults to a percent, or "Indeterminate" when value is nil.
show_value	boolean	No	Renders a data-part="value" readout. Defaults to false.
class	any	No	Extra classes for the root.
label_class	any	No	Extra classes for data-part="label".
value_class	any	No	Extra classes for data-part="value".
track_class	any	No	Extra classes for data-part="track".
indicator_class	any	No	Extra classes for data-part="indicator".
rest	global	No	Any other HTML attributes forwarded to the root element.

Progress CLI Arguments

Name	Type	Options	Recommended?
`--type`	string	progress	Yes
`--only`	string	progress	Yes
`--module`	string	Something	NO