# `PetalComponents.Progress`
[🔗](https://github.com/petalframework/petal_components/blob/v4.16.1/lib/petal_components/progress.ex#L1)

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.

# `progress`

## 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`

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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*