Assessment and survey

Single-choice matrix

<forma-matrix-single>

Repeated single-choice scales arranged as a matrix while retaining per-row radio semantics.

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

Purpose

A single-choice matrix asks the same scale question about several items. It looks like a table, but it is built from nested fieldsets: the outer fieldset names the whole set and each row is its own fieldset with its own radio group. Screen readers therefore announce the row prompt and the choice label for every radio, and each row validates independently. On narrow screens the rows decompose into ordinary stacked controls rather than relying on horizontal scrolling.

Use when

  • Several items are rated on the same short scale, such as maturity per practice or satisfaction per feature.
  • Each row is an independent required or optional answer.
  • Users benefit from comparing their answers across rows at a glance on wide screens.

Avoid when

  • There is only one item: use Ordinal scale.
  • Rows need different scales or long option descriptions: use separate Question shell shells.
  • The data is read-only and tabular: use Data grid or Comparison grid.
  • Items must be ordered relative to each other rather than rated independently: use Ranking.

Behavior to know

  • One name per row; rows never share a radio group.
  • Each row's legend is floated into the first grid column so the row reads as prompt then choices.
  • Choice labels are repeated in every row, so no column header is needed for assistive technology.
  • Below 44rem each row becomes a vertical list of full-width choices.

Basic example

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

Canonical

Minimal single-choice matrix

Rendered from the canonical pattern file.

Rate each practice.

Each row is an independent single-choice question. On narrow screens rows stack into ordinary controls.

Automated testing
Deployment automation
HTML · Minimal single-choice matrix Raw HTML for HTML · Minimal single-choice matrix
<forma-matrix-single class="forma-component-tag">
<fieldset class="forma-matrix">
  <legend class="forma-matrix__legend">Rate each practice.</legend>
  <p class="forma-field__description">Each row is an independent single-choice question. On narrow screens rows stack into ordinary controls.</p>

  <div class="forma-matrix__rows">
    <fieldset class="forma-matrix__row">
      <legend>Automated testing</legend>
      <div class="forma-matrix__choices">
        <label><input type="radio" name="testing-maturity" value="1" required><span>Initial</span></label>
        <label><input type="radio" name="testing-maturity" value="2"><span>Developing</span></label>
        <label><input type="radio" name="testing-maturity" value="3"><span>Established</span></label>
        <label><input type="radio" name="testing-maturity" value="4"><span>Optimized</span></label>
      </div>
    </fieldset>

    <fieldset class="forma-matrix__row">
      <legend>Deployment automation</legend>
      <div class="forma-matrix__choices">
        <label><input type="radio" name="deployment-maturity" value="1" required><span>Initial</span></label>
        <label><input type="radio" name="deployment-maturity" value="2"><span>Developing</span></label>
        <label><input type="radio" name="deployment-maturity" value="3"><span>Established</span></label>
        <label><input type="radio" name="deployment-maturity" value="4"><span>Optimized</span></label>
      </div>
    </fieldset>
  </div>
</fieldset>
</forma-matrix-single>

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

Examples

Scenario

Partially answered with a row error

Three satisfaction rows after an attempted submit. Two are answered; the unanswered row has aria-invalid and a validation message referenced from its fieldset.

How satisfied are you with each tool?
Issue tracker
Continuous integration

Rate continuous integration before continuing.

Chat
HTML · Partially answered with a row error Raw HTML for HTML · Partially answered with a row error
<forma-matrix-single class="forma-component-tag">
  <fieldset class="forma-matrix">
    <legend class="forma-matrix__legend">How satisfied are you with each tool?</legend>
    <div class="forma-matrix__rows">
      <fieldset class="forma-matrix__row">
        <legend>Issue tracker</legend>
        <div class="forma-matrix__choices">
          <label><input type="radio" name="matrix-partial-tracker" value="1" required><span>Unsatisfied</span></label>
          <label><input type="radio" name="matrix-partial-tracker" value="2"><span>Neutral</span></label>
          <label><input type="radio" name="matrix-partial-tracker" value="3" checked><span>Satisfied</span></label>
        </div>
      </fieldset>
      <fieldset class="forma-matrix__row" aria-describedby="matrix-partial-ci-error">
        <legend>Continuous integration</legend>
        <div class="forma-matrix__choices">
          <label><input type="radio" name="matrix-partial-ci" value="1" required aria-invalid="true"><span>Unsatisfied</span></label>
          <label><input type="radio" name="matrix-partial-ci" value="2" aria-invalid="true"><span>Neutral</span></label>
          <label><input type="radio" name="matrix-partial-ci" value="3" aria-invalid="true"><span>Satisfied</span></label>
        </div>
      </fieldset>
      <p class="forma-validation-message" id="matrix-partial-ci-error">
        <span class="forma-validation-message__mark" aria-hidden="true">!</span>
        Rate continuous integration before continuing.
      </p>
      <fieldset class="forma-matrix__row">
        <legend>Chat</legend>
        <div class="forma-matrix__choices">
          <label><input type="radio" name="matrix-partial-chat" value="1" required checked><span>Unsatisfied</span></label>
          <label><input type="radio" name="matrix-partial-chat" value="2"><span>Neutral</span></label>
          <label><input type="radio" name="matrix-partial-chat" value="3"><span>Satisfied</span></label>
        </div>
      </fieldset>
    </div>
  </fieldset>
</forma-matrix-single>

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

Scenario

Long row prompts with Not applicable

Row prompts that wrap over several lines, and a fifth Not applicable column that is a real answer in each row. The prompt column keeps a 10rem minimum and wraps.

How consistently does your team follow these practices?

Choose Not applicable only when the practice does not apply to your service.

Every schema migration is reviewed and has a tested rollback path
Feature flags older than 90 days are removed or made permanent
HTML · Long row prompts with Not applicable Raw HTML for HTML · Long row prompts with Not applicable
<forma-matrix-single class="forma-component-tag">
  <fieldset class="forma-matrix">
    <legend class="forma-matrix__legend">How consistently does your team follow these practices?</legend>
    <p class="forma-field__description">Choose Not applicable only when the practice does not apply to your service.</p>
    <div class="forma-matrix__rows">
      <fieldset class="forma-matrix__row">
        <legend>Every schema migration is reviewed and has a tested rollback path</legend>
        <div class="forma-matrix__choices">
          <label><input type="radio" name="matrix-long-migrations" value="never" required><span>Never</span></label>
          <label><input type="radio" name="matrix-long-migrations" value="sometimes"><span>Sometimes</span></label>
          <label><input type="radio" name="matrix-long-migrations" value="usually"><span>Usually</span></label>
          <label><input type="radio" name="matrix-long-migrations" value="always"><span>Always</span></label>
          <label><input type="radio" name="matrix-long-migrations" value="na"><span>Not applicable</span></label>
        </div>
      </fieldset>
      <fieldset class="forma-matrix__row">
        <legend>Feature flags older than 90 days are removed or made permanent</legend>
        <div class="forma-matrix__choices">
          <label><input type="radio" name="matrix-long-flags" value="never" required><span>Never</span></label>
          <label><input type="radio" name="matrix-long-flags" value="sometimes"><span>Sometimes</span></label>
          <label><input type="radio" name="matrix-long-flags" value="usually"><span>Usually</span></label>
          <label><input type="radio" name="matrix-long-flags" value="always"><span>Always</span></label>
          <label><input type="radio" name="matrix-long-flags" value="na"><span>Not applicable</span></label>
        </div>
      </fieldset>
    </div>
  </fieldset>
</forma-matrix-single>

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

Matrix decomposed on a phone

At phone width each row becomes a stacked list of choices under its own prompt; no horizontal scrolling is required.

Viewport width

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

What changes at narrow widths

  • Below 44rem the row grid becomes one column: the row prompt sits above its choices.
  • Choices switch from columns to a single vertical list; each choice is a full-width 44px-tall row with left-aligned text.
  • Rows stay separate bordered groups, so it remains clear which choices belong to which item.
  • There is no horizontal scroll at 320px; adding columns lengthens the list instead.
HTML · Matrix decomposed on a phone Raw HTML for HTML · Matrix decomposed on a phone
<forma-matrix-single class="forma-component-tag">
  <fieldset class="forma-matrix">
    <legend class="forma-matrix__legend">Rate each capability.</legend>
    <div class="forma-matrix__rows">
      <fieldset class="forma-matrix__row">
        <legend>Alerting</legend>
        <div class="forma-matrix__choices">
          <label><input type="radio" name="matrix-mobile-alerting" value="1" required><span>Initial</span></label>
          <label><input type="radio" name="matrix-mobile-alerting" value="2"><span>Developing</span></label>
          <label><input type="radio" name="matrix-mobile-alerting" value="3"><span>Established</span></label>
        </div>
      </fieldset>
      <fieldset class="forma-matrix__row">
        <legend>Runbooks</legend>
        <div class="forma-matrix__choices">
          <label><input type="radio" name="matrix-mobile-runbooks" value="1" required><span>Initial</span></label>
          <label><input type="radio" name="matrix-mobile-runbooks" value="2" checked><span>Developing</span></label>
          <label><input type="radio" name="matrix-mobile-runbooks" value="3"><span>Established</span></label>
        </div>
      </fieldset>
    </div>
  </fieldset>
</forma-matrix-single>

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
typeinputradio—Required. One radio per choice in each row.
nameinputstring unique per row—Each row has its own name, so each row is its own exclusive answer.
valueinputstring—Submitted value for the row. Meaning and scoring stay in the application.
requiredfirst input of a rowbooleanabsentMakes that row's answer required; rows validate independently.
checkedinputbooleanabsentRestores a saved row answer.
aria-invalidinputs of a rowtrueabsentSet by the application on a row that failed validation.
aria-describedbyrow fieldsetid of an error or help element—Associates a row-level error or help text with that row.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-matrixBlock class—Outer fieldset for the whole set, with browser border and padding removed.
.forma-matrix__choicesElement class—Equal columns of at least 5rem for the row's choices; each label is a bordered 44px-tall cell and the radio is visually hidden.
.forma-matrix__legendElement class—Question text for the whole matrix.
.forma-matrix__rowElement class—Bordered fieldset for one item: prompt column plus choices column. Its legend is floated into the first column.
.forma-matrix__rowsElement class—Grid stacking the rows with a small gap.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves from one row's radio group to the next; each row is one tab stop.
Arrow keysMoves and selects within the current row only.
SpaceSelects the focused choice when the row is unanswered.
Events
EventDescription
input / changeNative events from each row's radio group.

Form behavior

Every row submits its own name=value. Unanswered rows submit nothing; required rows block submission independently.

States

Single-choice matrix states
StateHow it is expressedPresentation
Unanswered rowno checked radio in the rowAll cells neutral.
Selected:checkedThe chosen cell takes the inverse surface.
Focus:focus-visible on the radioTwo-tone focus ring around the cell.
Invalid rowaria-invalid plus an application messageForma adds no row error styling; render a Validation message and reference it from the row.

Accessibility

Forma provides

  • Keeps every row as its own fieldset with a legend, so the row prompt is announced with each radio.
  • Repeats choice text in every cell, avoiding reliance on a visual column header.
  • Decomposes to ordinary stacked controls at narrow widths instead of forcing horizontal scroll.
  • Uses Highlight/HighlightText for the checked cell in forced-colors mode.

Your application supplies

  • Give each row a unique radio name.
  • Keep choice labels short; long descriptions do not fit matrix cells.
  • Associate row errors with the row fieldset and summarise multiple errors with Validation summary.

Responsive behavior

  • Wide: each row is a grid of minmax(10rem, 1.1fr) for the prompt and minmax(0, 3fr) for the choices.
  • Choice columns are at least 5rem; many choices on a medium width can crowd, so keep scales short.
  • Below 44rem the row becomes one column and the choices become a vertical list of full-width cells.
  • Row prompts and choice text wrap; there is no horizontal scrolling path.

Motion

  • No animation beyond native state: the checked cell switches surface immediately. Cells are not part of the shared transitioned option families.

Usage guidance

Do

  • Use the same choices in the same order for every row.
  • Keep the number of rows modest and group long sets into sections.

Avoid

  • Sharing one radio name across rows.
  • Replacing the per-cell labels with a single header row.

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.