PetalComponents.Progress (petal_components v4.16.0)

Copy Markdown View Source

Determinate progress in two shapes, sharing one API.

  • progress/1 - the linear bar. Page-top loading strips, upload rows, quota meters.
  • progress_ring/1 - the circular version. Reads at sizes a bar can't (a 16px ring in a table cell still shows its proportion), and at lg and up the middle is free real estate for a percentage readout.

Both take the same value/max, the same size scale (xs to xl) and the same color vocabulary, so a bar and a ring on the same page agree.

Below lg the readout belongs beside the ring, not inside it - see the showcase for the pairing.

What this is not

Both shapes are determinate: you know the percentage and you're showing it. For "something is happening, no idea how long" reach for PetalComponents.Loading.spinner/1 instead. A ring that spins forever is a spinner wearing a progress costume, and this library already has a spinner.

Semi-circle gauges (the speedometer look) are deliberately absent. They're a dashboard-chart shape rather than a progress shape, and nobody has asked.

Summary

Functions

progress(assigns)
progress_ring(assigns)

Circular determinate progress: a track ring with the value drawn as an arc over it, starting at 12 o'clock and going clockwise.

Functions

progress(assigns)

Attributes

  • size (:string) - Defaults to "md". Must be one of "xs", "sm", "md", "lg", or "xl".
  • color (:string) - Defaults to "primary". Must be one of "primary", "secondary", "info", "success", "warning", "danger", or "gray".
  • label (:string) - labels your progress bar. Defaults to nil.
  • label_position (:string) - inside renders the label in the bar itself (xl only); top renders a label row with the percentage above the bar, at any size. Defaults to "inside". Must be one of "inside", or "top".
  • value (:integer) - adds a value to your progress bar. Defaults to nil.
  • max (:integer) - sets a max value for your progress bar. Defaults to 100.
  • status (:string) - a status line under the bar - "Downloading assets..." - announced politely to screen readers as it changes. Defaults to nil.
  • class (:any) - CSS class. Defaults to nil.
  • Global attributes are accepted.

progress_ring(assigns)

Circular determinate progress: a track ring with the value drawn as an arc over it, starting at 12 o'clock and going clockwise.

<.progress_ring value={72} />
<.progress_ring value={72} size="lg" color="success" show_value />
<.progress_ring value={12} max={30} size="lg"><span>12/30</span></.progress_ring>

The arc is stroke="currentColor" and the track is the same colour washed back, so a text class recolours the whole thing the way it does on PetalComponents.Sparkline.sparkline/1:

<.progress_ring value={72} class="text-emerald-500" />

size sets the diameter (16px at xs up to 96px at xl); a w-*/h-* class overrides it and the stroke scales with the box.

Attributes

  • size (:string) - Defaults to "md". Must be one of "xs", "sm", "md", "lg", or "xl".
  • color (:string) - Defaults to "primary". Must be one of "primary", "secondary", "info", "success", "warning", "danger", or "gray".
  • value (:integer) - how far along you are. Defaults to nil.
  • max (:integer) - sets a max value for your progress ring. Defaults to 100.
  • label (:string) - the accessible name, same as on the bar - not drawn, screen readers only. Defaults to nil.
  • show_value (:boolean) - draws the rounded percentage in the middle. lg and xl only - below that the hole is too small to read a number in, so it draws nothing and the readout goes beside the ring. Defaults to false.
  • class (:any) - CSS class. Defaults to nil.
  • Global attributes are accepted.

Slots

  • inner_block - custom middle content ("12/30", an icon) - takes over from show_value, and unlike show_value it renders at every size, so below lg keep it to something that survives a 40px hole.