Meter

A meter reads a measurement. A progress bar tracks how far a task has got. On the web the two differ mainly in semantics: role="meter" against role="progressbar". Mob exposes no such role, and both components are a proportional fill along a track, so Meter draws the same native bar as Mob Progress and shares its range math.

You pass a value inside [min, max], which is 0 to 100 by default. The component clamps it, so a value outside the range draws a full or empty gauge. The default readout is the rounded percentage of the range. Set value_text to replace it, and show_value to show it beside the label.

A meter always reads something. Leave out value and you get an empty gauge, never the animated indeterminate bar that Progress draws for the same input.

Meter has no events. The screen owns the measurement: change the assign that you pass as value and the gauge follows. The buttons in the examples below belong to the screen.

Run this from your Mob app's root to add the component to lib/<app>/components/:

mix mishka.ui.gen.mob meter

The generator registers the tag, so you can use it in ~MOB markup. Meter calls Progress, so the generator also generates the progress component. The examples on this page use the mishka_ prefix of the showcase app (--module-prefix mishka_), so the tag is <MishkaMeter>. Without a prefix, the tag is <Meter>.

A meter shows a measurement with its own readout. Pass value, a label and show_value. In the showcase app, the Free up and Fill up buttons change the measurement, and the gauge follows.

Meter gauge

LTR RTL

Preview

Show the whole example Show less

Left: the example as it loads. Right: after a tap. A meter reads a measurement and moves with it.

<MishkaMeter value={@used} label="Storage" show_value={true} />

min and max map the scale onto the gauge, and value_text replaces the percentage, so the signal reads 3 of 5 bars. The screenshot also shows a temperature gauge that runs from 20 to 40.

Meter with any range

LTR RTL

Preview

Show the whole example Show less

<MishkaMeter
  value={3}
  max={5}
  label="Signal"
  value_text="3 of 5 bars"
  show_value={true}
/>

A value outside the range does not overshoot. A value of 250 draws a full gauge, and a value of -40 draws an empty one. A meter with no value also reads empty. The screenshot shows both clamped gauges and an Unknown gauge with no value.

Meter values outside the range

LTR RTL

Preview

Show the whole example Show less

<MishkaMeter value={250} />   # renders full
<MishkaMeter value={-40} />   # renders empty

color tints the fill, and height sets how thick the gauge is. A meter reads a measurement, so the color usually carries the warning, and a thick gauge is easier to read at a glance than a thin one. In the snippet, band/1 is a function in your screen that picks red, amber or green from the value, so the gauge warns before the reader sees the number. On iOS the native gauge ignores height. See Draw the meter with render box below.

Meter color and thickness

LTR RTL

Preview

Show the whole example Show less

# height is the gauge's thickness; the default is the platform's ~4dp.
<MishkaMeter value={91} color={0xFFDC2626} height={18} />

# Colour from the value, so the gauge warns before the number is read.
defp band(v) when v >= 85, do: 0xFFDC2626
defp band(v) when v >= 60, do: 0xFFF59E0B
defp band(_v), do: 0xFF16A34A

Set render={:box} to replace the native bar with a track Box that holds a fill Box. Then width, height, corner_radius, track_color and color describe the gauge exactly, instead of nudging the platform's own bar.

<MishkaMeter value={@used} render={:box}
             width={46} height={6} corner_radius={3}
             track_color={:transparent} color={0xFFFF7A00} />

A meter suits the drawn form well. The one thing a drawn bar cannot do is animate, and the only state that needs animation is the indeterminate bar of Progress. A meter has no such state, because every meter has a value to draw. An empty gauge draws no fill, and a full gauge fills the track.

The drawing props (render, width, track_color, corner_radius and id) pass straight through to Progress, which documents each one in full. :progress stays the default because a drawn gauge inherits none of the platform bar's metrics.

• The *_class attributes are not ported. They style DOM parts.
• There is no role="meter". Mob exposes no such role.
• ratio/1 returns the fill ratio from 0.0 to 1.0. It is the native equivalent of the web component's --chelekom-meter custom property.

• Headless Meter, the web component this one ports.
• Mob Progress, the bar that tracks how far a task has got and owns the drawing that Meter uses.
• Mob Semi Circle Progress, a gauge that shows a value as a half circle.
• Mob Separator, a rule that divides groups of content.
• Mob components, the full list of native components.