Progress

<o-progress> fills a lane up to a value, over a track that shows the whole range. It is the base of progress rings, gauges and meters.

A progress goes straight into a ring, one per ring: put each bar of a multi-bar meter on its own ring. It is drawn by the runtime, so it needs the Orbit script. For screen readers, give it role="progressbar" and the aria- values, as above.

Reference

AttributeDefaultWhat it does
value0Progress, out of max.
max100The value that fills the ring's range. Without it, --o-max of the ring or system.
shapenoneThe ending. See Endings.
variantstroke draws thin lines instead of filled bands. See Stroke variant.
interactiveMakes the whole track clickable, whatever its colors. See Pointer interaction.
hit-width0Extra touch area, in px, on each side of an interactive track.
Property or classDefaultWhat it does
--o-progressThe value, set from CSS. Wins over value.
--o-max100The scale: the value that fills the range when there is no max attribute. Cascades from the ring and the system.
--o-value-angleread onlyWritten on the ring: the angle of the value from the start of the range. A .satellite.at-value sits there. See A satellite on the value.
--o-fillvar(--o-gray-light)Bar color. Not used by variant="stroke".
--o-strokevar(--o-fill)Bar outline, or the line color with variant="stroke".
--o-stroke-width1 (2 with stroke)Bar outline width, or the line width, in px.
--o-back-filltransparentTrack color. Not used by variant="stroke".
--o-back-strokenone (gray with stroke)Track outline, or the track line color.
--o-back-stroke-width1Track outline or line width, in px.
--o-size-ratio1Thickness, in lanes. .grow-* and .shrink-* work as on satellites.
.inner-orbit, .outer-orbit, .quarter-*-orbitMoves the band in or out from its lane.
.angle-0 … .angle-360Starts the bar at that angle instead of the ring's --o-from.

Value and color

value runs from 0 to max (100 by default) and fills that share of the ring's range. --o-max on a ring or system sets max for every progress and arc below it that has none. --o-fill colors the bar and --o-back-fill the track behind it; --o-stroke and --o-back-stroke outline them.

--o-progress sets the value from CSS and wins over the attribute. Use it when a class or a parent owns the state:

Outer ring: --o-progress from a class. Inner ring: value="50" max="80", with an outlined track.

Orbit redraws when the element's attributes change, and when a class or an inline --o-* property changes on it or on an ancestor. After a change it cannot see, such as editing a stylesheet rule or a :hover rule that changes the geometry, call Orbit.refresh(). The value does not animate: a transition on --o-progress jumps straight to the new value.

Gauges

A progress fills the ring's range, so a partial range makes a gauge. range-240 from-240 leaves the gap at the bottom:

A satellite on the value

A .satellite.at-value in the same ring sits on the value of the progress: the knob of a dial, a marker, a tip. The progress writes the angle of its value on its ring as --o-value-angle, so the satellite follows every change. It sits on the middle of the band; outer-orbit or --o-alignment move it in or out, as on any satellite.

Drag along the band, or focus it and use the arrow keys. The knob is a satellite with at-value; nothing computes its angle.

Progress always fills clockwise, so at-value ignores ccw. With more than one progress in a ring, the satellite follows the last one drawn.

Endings

shape sets how the bar ends: circle (or circle-a), circle-b, bullet, arrow, slash, backslash, rounded and zigzag. Endings are sized from the band, so they look the same on every ring and at every size.

Stroke variant

By default the bar is a filled band. For a thin gauge line, add variant="stroke": the bar and the track become lines along the middle of the lane, with round caps.

  • --o-stroke colors the line and --o-back-stroke the track. --o-fill and --o-back-fill are not used.
  • The line is 2px wide (--o-stroke-width) and the track 1px (--o-back-stroke-width), in screen pixels at any size.
  • The track is gray by default; set --o-back-stroke to color it, or none to hide it.
  • shape does not apply. A full value on a 360° range draws a closed circle.
From the outside in: an 8px line, a tinted track, a full circle, and a 270° gauge.

Thickness and position

A progress is one lane thick. Set --o-size-ratio in lanes on the element, its ring or the .gravity-spot, or use the .grow-* and .shrink-* classes on the element. .inner-orbit and .outer-orbit move the band in or out so one of its edges sits on the lane, and the .quarter- versions go part of the way. A band two lanes thick on orbit-11 ends exactly at the edge of the universe.

Three rings, their thickness set once on the .gravity-spot. At 2 lanes they touch each other and the edge.

Pointer interaction

<o-progress> is decorative by default, so it never steals clicks from controls nearby. interactive makes the whole track clickable, including the part the bar does not cover, whatever its colors. hit-width adds touch area in px on each side, which helps with thin bars on touch screens.

Each click on the thin track, or up to 12px around it, adds 10.

When a progress acts as a control, you bring the keyboard behavior and the accessible name. It is placed with the rotate property, so your own transform or scale adds to it instead of replacing it.

After drawing

Each <o-progress> fires a bubbling o-rendered event after it redraws. To wait for everything on the page, for example before measuring, use await Orbit.ready(). See Runtime and resizing.