Assessment and survey

Survey progress

<forma-survey-progress>

Determinate progress using the native progress element plus explicit current/total text.

Authoring tag
<forma-survey-progress>
Behavior owner
Native HTML
Canonical source
patterns/survey-progress.html

Purpose

Survey progress tells respondents where they are in a questionnaire: a label, an explicit "Question 3 of 12" value, a native progress bar and optional section context. The text is the primary information; the bar reinforces it. All values come from the application, which defines what progress means (questions, pages or sections) and recalculates it when branching changes the total. Forma never decides whether work is complete.

Use when

  • A survey or assessment spans several questions or pages and respondents benefit from knowing how far along they are.
  • The current position and total are known (determinate progress).
  • Section context helps orient the respondent.

Avoid when

Behavior to know

  • Native progress with value and max, labelled by the visible label.
  • Explicit current/total text in monospace so users do not have to estimate the bar.
  • Accent color via accent-color; the bar keeps the platform's rendering.
  • Header wraps on narrow screens; the bar is always full width.

Basic example

The smallest correct markup: the canonical pattern from patterns/survey-progress.html inside its public tag. Copy this first, then adapt labels, names and state.

Canonical

Minimal survey progress

Rendered from the canonical pattern file.

Survey progress Question 3 of 12
25%

Section 1 of 4 · Governance

HTML · Minimal survey progress Raw HTML for HTML · Minimal survey progress
<forma-survey-progress class="forma-component-tag">
<div class="forma-survey-progress">
  <div class="forma-survey-progress__header">
    <span class="forma-survey-progress__label" id="survey-progress-label">Survey progress</span>
    <span class="forma-survey-progress__value">Question 3 of 12</span>
  </div>
  <progress class="forma-survey-progress__bar" value="3" max="12" aria-labelledby="survey-progress-label">25%</progress>
  <p class="forma-survey-progress__context">Section 1 of 4 · Governance</p>
</div>
</forma-survey-progress>

Click or tap the code once to select all of it, then copy.

Examples

Scenario

Page-based progress after branching

Progress measured in pages. An earlier answer removed a section, so the application recalculated the total from 6 to 5 pages and says so in the context line.

Assessment progress Page 2 of 5
40%

Security section skipped based on your earlier answer.

HTML · Page-based progress after branching Raw HTML for HTML · Page-based progress after branching
<forma-survey-progress class="forma-component-tag">
  <div class="forma-survey-progress">
    <div class="forma-survey-progress__header">
      <span class="forma-survey-progress__label" id="survey-page-label">Assessment progress</span>
      <span class="forma-survey-progress__value">Page 2 of 5</span>
    </div>
    <progress class="forma-survey-progress__bar" value="2" max="5" aria-labelledby="survey-page-label">40%</progress>
    <p class="forma-survey-progress__context">Security section skipped based on your earlier answer.</p>
  </div>
</forma-survey-progress>

Click or tap the code once to select all of it, then copy.

Scenario

All questions answered

The final question is answered and the bar is full. The text tells the respondent what happens next; a full bar alone does not mean the application has accepted the submission.

Survey progress 12 of 12 answered
100%

Review your answers, then submit.

HTML · All questions answered Raw HTML for HTML · All questions answered
<forma-survey-progress class="forma-component-tag">
  <div class="forma-survey-progress">
    <div class="forma-survey-progress__header">
      <span class="forma-survey-progress__label" id="survey-done-label">Survey progress</span>
      <span class="forma-survey-progress__value">12 of 12 answered</span>
    </div>
    <progress class="forma-survey-progress__bar" value="12" max="12" aria-labelledby="survey-done-label">100%</progress>
    <p class="forma-survey-progress__context">Review your answers, then submit.</p>
  </div>
</forma-survey-progress>

Click or tap the code once to select all of it, then copy.

Mobile

Each mobile example renders in its own document inside a real narrow viewport, so Forma's media and container queries run exactly as they would on a phone. Choose a width to compare.

Mobile example

Long section name on a phone

A long label and value at phone width. The header wraps onto two lines while the bar stays full width.

Viewport width

Frames narrower than the selected width show the component at the width available.

What changes at narrow widths

  • The header is a wrapping flex row: when label and value do not fit side by side, the value drops to its own line.
  • The bar is always 100% of the available width, so the proportion stays readable.
  • Section context wraps as normal text; nothing is truncated.
  • No horizontal overflow at 320px in either orientation.
HTML · Long section name on a phone Raw HTML for HTML · Long section name on a phone
<forma-survey-progress class="forma-component-tag">
  <div class="forma-survey-progress">
    <div class="forma-survey-progress__header">
      <span class="forma-survey-progress__label" id="survey-mobile-label">Operational readiness assessment</span>
      <span class="forma-survey-progress__value">Question 17 of 40</span>
    </div>
    <progress class="forma-survey-progress__bar" value="17" max="40" aria-labelledby="survey-mobile-label">43%</progress>
    <p class="forma-survey-progress__context">Section 3 of 6 · Incident response and communication</p>
  </div>
</forma-survey-progress>

Click or tap the code once to select all of it, then copy.

Baseline

Mobile · 320px

The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.

Viewport width

Frames narrower than the selected width show the component at the width available.

API and configuration

Forma components have no JavaScript API. Their public contract is the markup: native elements and attributes you write, and the CSS hooks below. The CSS hook table is generated from the built stylesheet, so it always matches the shipped implementation.

Native and ARIA attributes
AttributeOnValuesDefaultDescription
valueprogressnumber—Current position supplied by the application.
maxprogressnumber1Total supplied by the application; update it when branching changes the total.
aria-labelledbyprogressid of .forma-survey-progress__label—Gives the bar its accessible name.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-survey-progressBlock class—Root grid stacking header, bar and context.
.forma-survey-progress__barElement class—The native progress element: full width, 0.65rem tall, accent color from the theme.
.forma-survey-progress__contextElement class—Optional section or status text under the bar.
.forma-survey-progress__headerElement class—Wrapping flex row with label and value at opposite ends.
.forma-survey-progress__labelElement class—Bold visible label; reference it from the bar.
.forma-survey-progress__valueElement class—Explicit current/total text in small monospace.
Keyboard interaction
KeysResult
NoneNot interactive and not focusable.

Form behavior

Does not participate in forms.

States

Survey progress states
StateHow it is expressedPresentation
In progressvalue < maxPartially filled bar with explicit text.
Fullvalue = maxBar filled. Completion is still decided by the application.
Recalculatedapplication changes maxThe bar and text reflect the new total; explain the change in context text.

Accessibility

Forma provides

  • Uses the native progress element, exposing value and max as a progressbar to assistive technology.
  • Shows current/total as text, so the state does not depend on reading the bar.
  • Provides fallback content inside the progress element for older user agents.

Your application supplies

  • Keep the value text, value and max in sync.
  • Describe what the numbers count (questions, pages, sections).
  • Do not announce every change with a live region; update quietly and let users query it.

Responsive behavior

  • Header wraps as a flex row with a 1rem gap.
  • The bar is always full width.
  • No breakpoints; context text wraps normally.

Motion

  • No animation: the bar's fill is rendered by the browser and changes immediately when the application writes a new value.

Usage guidance

Do

  • Place progress at the top of each survey page, in the same position every time.
  • Recalculate totals when branching changes them, and say so.

Avoid

  • Showing a bar without the explicit current/total text.
  • Using a full bar as the signal that the survey has been submitted.

Verification specimens

Generated fault-injection specimens expose content, spacing, color-cue, and reduced-effective-contrast risks. They screen presentation robustness as engineering screens without claiming human-subject validation.