Display form control

Progress

<ut-progress>

Show progress as a bar, a ring or named steps from two fields of the form or fixed values, with warning and on-track colours.

Officialv1.0.0 Self-contained

Download .utpkg 15 KB Install in your workspace

Try it

Live preview

The real control in the same sandboxed frame the app uses. Switch to dark mode or read-only to see how it adapts.

Onboarding checklist

Value the form receives

null

Sandboxed frame (opaque origin, its own CSP), talking to this page only through the typed postMessage bridge — exactly as on a form.

About

What it does

Show people where things stand without making them do the maths: tasks done out of the onboarding checklist, hours used of a budget, items received of an order, or the stage a request has reached (Submitted, Review, Approval, Done). Map the Current and Total context entries to fields of the form (numbers, a step name, or a list whose length counts), or type fixed values.

Choose a bar, a ring or a row of steps, a unit and your own label ("{{remaining}} hours left"). Set Warn below and Good from to turn the progress red with Needs attention or green with On track, so colour is never the only signal. Screen readers hear a real progressbar with the full text ("7 of 12 tasks, 58%"), and the steps style is an ordered list with the current step marked ("Step 2 of 5: Review"). It is display only and never changes the form's data.

Good for

Onboarding checklist: tasks done out of the total
Budget or hours used against the allowance, red when nearly exhausted
Where a request is in its approval stages

After installing

Install the package: Progress appears in Extensibility → Form controls and in the form designer's palette under Custom.
Drag Progress onto a form and choose the style (bar, ring or steps).
Map the Current (and optionally Total) context entries to fields of the form, or type Current / Total values. For steps, list the step names.
Optionally set the unit, the label, and the Warn below / Good from thresholds.

Reference

Value, properties and accessibility

Value

number

Stored as the field's value (type number), validated by the server against the control's schema.

Read-only views (completed tasks, mobile, emails) show the value as text.

Keyboard and screen readers

Role: progressbar, named by the field label.

Display only: nothing to operate. Bar and ring are a progressbar with the label and percentage as aria-valuetext; Steps is an ordered list with the current step marked aria-current="step" ("Step 2 of 5: Review").

Properties (set in the form designer)
Property	Type	Default	What it does
Style `appearance`	Bar / Ring / Steps	bar
Current `current_value`	number	—	Used when the Current context entry is not mapped.
Total `total_value`	number	100	Used when the Total context entry is not mapped. For Steps, the number of steps.
Step names `steps`	list	—	For the Steps style, in order (e.g. Submitted, Review, Approval, Done). Current may be the step number (1 = first) or its name.
Unit `unit`	string	—	e.g. tasks, hours, $
Show percentage `show_percentage`	boolean	yes
Label `label_template`	string	—	Text with {{current}}, {{total}}, {{unit}}, {{percent}}, {{remaining}}, {{step}}. Default: {{current}} of {{total}} {{unit}}.
Warn below (%) `warn_below`	number 0–100	—	Below this percentage the progress uses the error colour and says Needs attention.
Good from (%) `good_above`	number 0–100	—	From this percentage the progress uses the success colour and says On track.

Context (other fields it reads)

current — Current: The field with the progress so far (a number, a step number or name, or a list whose length counts).
total — Total: The field with the target or total (a number, or a list whose length counts).

The designer maps each one to a field of the same form; the control receives those values read-only.

Install

Install it in your workspace

Works on UserTasks cloud and any self-hosted instance. The control lands in Extensibility → Form controls, enabled, and appears in the form designer's Custom palette.

In the app

Open Extensibility → Form controls → Browse gallery (it opens Packages → Browse gallery on the Form controls tab) and choose Install on Progress. Or download form-control-progress-1.0.0.utpkg and drag it onto Automations → Packages.
The wizard verifies the checksum, every file hash and the signature, and shows what it adds.
Drag the control onto a form in the designer and set its properties.

With the CLI

shell

curl -fLO https://usertasks.com/gallery/form-control-progress-1.0.0.utpkg
usertasks packages inspect form-control-progress-1.0.0.utpkg
usertasks packages install form-control-progress-1.0.0.utpkg

Verify the download

File SHA-256: df28667e7bafb6c6c8981440ecd9b7b3c473406ae93afbf2084e22032630a730
Package checksum (what is signed): sha256:efe1767fd75fbea584a1d2f004b198916d24d2d12d972d93286dc1f92f35c709
<ut-progress> module SHA-256: ba08a02f66a291f23178d2356f1f80ebb75692929f48520c830fecff5b5b5281
Signer: UserTasks Gallery · 49:f3:04:90:47:02:4d:07:28:61:3d:dc:bb:aa:db:11

More form controls

All controls