Assessment and survey

Symbol rating

<forma-symbol-rating>

Ordinal rating presented with symbols while retaining accessible textual labels.

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

Purpose

A symbol rating presents an ordinal scale as a row of stars or other glyphs. Each glyph is a native radio in one group; the glyph is decorative (aria-hidden) and every option carries visually hidden text stating its position and meaning, such as "4 of 5, satisfied". Only the chosen symbol is highlighted: Forma does not fill preceding symbols, so the selected position is never implied by a run of color alone.

Use when

  • A familiar star or icon rating suits the audience, such as satisfaction or quality feedback.
  • The scale has few positions and each has a textual meaning that can be announced.
  • Space is limited and a compact row of square targets fits better than a labelled scale.

Avoid when

  • Visible text labels are important for sighted users to interpret the answer: use Ordinal scale.
  • The rating is displayed, not entered: render text or a Badge, not radios.
  • The answer is a yes/no: use Binary choice.

Behavior to know

  • Each option is a square target at least 44 by 44px with a border.
  • The accessible name comes from .forma-sr-only text, never from the glyph.
  • The row wraps onto more lines when it does not fit.
  • Selection is shown on the chosen symbol only, as an inverse surface.

Basic example

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

Canonical

Minimal symbol rating

Rendered from the canonical pattern file.

How satisfied are you with the release process?
HTML · Minimal symbol rating Raw HTML for HTML · Minimal symbol rating
<forma-symbol-rating class="forma-component-tag">
<fieldset class="forma-symbol-rating">
  <legend class="forma-symbol-rating__legend">How satisfied are you with the release process?</legend>

  <div class="forma-symbol-rating__options">
    <label class="forma-symbol-rating__option">
      <input type="radio" name="release-satisfaction" value="1" required>
      <span class="forma-symbol-rating__symbol" aria-hidden="true">★</span>
      <span class="forma-sr-only">1 of 5, very dissatisfied</span>
    </label>
    <label class="forma-symbol-rating__option">
      <input type="radio" name="release-satisfaction" value="2">
      <span class="forma-symbol-rating__symbol" aria-hidden="true">★</span>
      <span class="forma-sr-only">2 of 5, dissatisfied</span>
    </label>
    <label class="forma-symbol-rating__option">
      <input type="radio" name="release-satisfaction" value="3">
      <span class="forma-symbol-rating__symbol" aria-hidden="true">★</span>
      <span class="forma-sr-only">3 of 5, neutral</span>
    </label>
    <label class="forma-symbol-rating__option">
      <input type="radio" name="release-satisfaction" value="4">
      <span class="forma-symbol-rating__symbol" aria-hidden="true">★</span>
      <span class="forma-sr-only">4 of 5, satisfied</span>
    </label>
    <label class="forma-symbol-rating__option">
      <input type="radio" name="release-satisfaction" value="5">
      <span class="forma-symbol-rating__symbol" aria-hidden="true">★</span>
      <span class="forma-sr-only">5 of 5, very satisfied</span>
    </label>
  </div>
</fieldset>
</forma-symbol-rating>

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

Examples

Scenario

Saved four-star rating

A response restored with the fourth option checked. Only that option is inverted; the text meaning is "4 of 5, satisfied".

How satisfied are you with the new onboarding guide?
HTML · Saved four-star rating Raw HTML for HTML · Saved four-star rating
<forma-symbol-rating class="forma-component-tag">
  <fieldset class="forma-symbol-rating">
    <legend class="forma-symbol-rating__legend">How satisfied are you with the new onboarding guide?</legend>
    <div class="forma-symbol-rating__options">
      <label class="forma-symbol-rating__option"><input type="radio" name="symbol-saved-onboarding" value="1" required><span class="forma-symbol-rating__symbol" aria-hidden="true">★</span><span class="forma-sr-only">1 of 5, very dissatisfied</span></label>
      <label class="forma-symbol-rating__option"><input type="radio" name="symbol-saved-onboarding" value="2"><span class="forma-symbol-rating__symbol" aria-hidden="true">★</span><span class="forma-sr-only">2 of 5, dissatisfied</span></label>
      <label class="forma-symbol-rating__option"><input type="radio" name="symbol-saved-onboarding" value="3"><span class="forma-symbol-rating__symbol" aria-hidden="true">★</span><span class="forma-sr-only">3 of 5, neutral</span></label>
      <label class="forma-symbol-rating__option"><input type="radio" name="symbol-saved-onboarding" value="4" checked><span class="forma-symbol-rating__symbol" aria-hidden="true">★</span><span class="forma-sr-only">4 of 5, satisfied</span></label>
      <label class="forma-symbol-rating__option"><input type="radio" name="symbol-saved-onboarding" value="5"><span class="forma-symbol-rating__symbol" aria-hidden="true">★</span><span class="forma-sr-only">5 of 5, very satisfied</span></label>
    </div>
  </fieldset>
</forma-symbol-rating>

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

Scenario

Three-level effort rating with a visible key

Non-star glyphs for a three-level effort question. A visible description spells out the key for sighted users, because distinct glyphs are not self-explanatory.

How much effort did the migration take?

● low, ●● moderate, ●●● high

HTML · Three-level effort rating with a visible key Raw HTML for HTML · Three-level effort rating with a visible key
<forma-symbol-rating class="forma-component-tag">
  <fieldset class="forma-symbol-rating" aria-describedby="symbol-effort-key">
    <legend class="forma-symbol-rating__legend">How much effort did the migration take?</legend>
    <p class="forma-field__description" id="symbol-effort-key">● low, ●● moderate, ●●● high</p>
    <div class="forma-symbol-rating__options">
      <label class="forma-symbol-rating__option"><input type="radio" name="symbol-effort-migration" value="low" required><span class="forma-symbol-rating__symbol" aria-hidden="true">●</span><span class="forma-sr-only">Low effort</span></label>
      <label class="forma-symbol-rating__option"><input type="radio" name="symbol-effort-migration" value="moderate"><span class="forma-symbol-rating__symbol" aria-hidden="true">●●</span><span class="forma-sr-only">Moderate effort</span></label>
      <label class="forma-symbol-rating__option"><input type="radio" name="symbol-effort-migration" value="high"><span class="forma-symbol-rating__symbol" aria-hidden="true">●●●</span><span class="forma-sr-only">High effort</span></label>
    </div>
  </fieldset>
</forma-symbol-rating>

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

Ten-point rating wrapping on a phone

Ten symbols do not fit one row at 320px, so the row wraps. Targets keep their size rather than shrinking.

Viewport width

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

What changes at narrow widths

  • The options row is an inline flex container with wrapping, so symbols continue on a second line when the width runs out.
  • Each option keeps its 2.75rem (44px) minimum width and height; targets are never compressed to force one line.
  • Reading and keyboard order stay left to right, top to bottom, matching the value order.
  • No horizontal scrolling at any width.
HTML · Ten-point rating wrapping on a phone Raw HTML for HTML · Ten-point rating wrapping on a phone
<forma-symbol-rating class="forma-component-tag">
  <fieldset class="forma-symbol-rating">
    <legend class="forma-symbol-rating__legend">Rate the clarity of the incident report.</legend>
    <div class="forma-symbol-rating__options">
      <label class="forma-symbol-rating__option"><input type="radio" name="symbol-mobile-clarity" value="1" required><span class="forma-symbol-rating__symbol" aria-hidden="true">★</span><span class="forma-sr-only">1 of 10, very unclear</span></label>
      <label class="forma-symbol-rating__option"><input type="radio" name="symbol-mobile-clarity" value="2"><span class="forma-symbol-rating__symbol" aria-hidden="true">★</span><span class="forma-sr-only">2 of 10</span></label>
      <label class="forma-symbol-rating__option"><input type="radio" name="symbol-mobile-clarity" value="3"><span class="forma-symbol-rating__symbol" aria-hidden="true">★</span><span class="forma-sr-only">3 of 10</span></label>
      <label class="forma-symbol-rating__option"><input type="radio" name="symbol-mobile-clarity" value="4"><span class="forma-symbol-rating__symbol" aria-hidden="true">★</span><span class="forma-sr-only">4 of 10</span></label>
      <label class="forma-symbol-rating__option"><input type="radio" name="symbol-mobile-clarity" value="5"><span class="forma-symbol-rating__symbol" aria-hidden="true">★</span><span class="forma-sr-only">5 of 10</span></label>
      <label class="forma-symbol-rating__option"><input type="radio" name="symbol-mobile-clarity" value="6"><span class="forma-symbol-rating__symbol" aria-hidden="true">★</span><span class="forma-sr-only">6 of 10</span></label>
      <label class="forma-symbol-rating__option"><input type="radio" name="symbol-mobile-clarity" value="7"><span class="forma-symbol-rating__symbol" aria-hidden="true">★</span><span class="forma-sr-only">7 of 10</span></label>
      <label class="forma-symbol-rating__option"><input type="radio" name="symbol-mobile-clarity" value="8"><span class="forma-symbol-rating__symbol" aria-hidden="true">★</span><span class="forma-sr-only">8 of 10</span></label>
      <label class="forma-symbol-rating__option"><input type="radio" name="symbol-mobile-clarity" value="9"><span class="forma-symbol-rating__symbol" aria-hidden="true">★</span><span class="forma-sr-only">9 of 10</span></label>
      <label class="forma-symbol-rating__option"><input type="radio" name="symbol-mobile-clarity" value="10"><span class="forma-symbol-rating__symbol" aria-hidden="true">★</span><span class="forma-sr-only">10 of 10, very clear</span></label>
    </div>
  </fieldset>
</forma-symbol-rating>

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 symbol.
nameinputstring—Groups the symbols into one answer. Unique per question.
valueinputstring—Submitted rating. Meaning and scoring stay in the application.
requiredfirst inputbooleanabsentNative required-group validation.
checkedinputbooleanabsentRestores a saved rating.
aria-hidden.forma-symbol-rating__symboltrue—Required. The glyph is decorative and must not be the accessible name.
aria-describedbyfieldsetid list—Associates a key or help text with the rating.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-symbol-ratingBlock class—Root fieldset with browser border and padding removed.
.forma-symbol-rating__legendElement class—Question text.
.forma-symbol-rating__optionElement class—Bordered square label, at least 44px each way. The radio inside is visually hidden.
.forma-symbol-rating__optionsElement class—Wrapping inline flex row of options with a 0.25rem gap.
.forma-symbol-rating__symbolElement class—The decorative glyph at 1.35rem.
.forma-sr-onlyBlock class—Visually hidden text that gives each option its accessible name, such as "3 of 5, neutral".
Keyboard interaction
KeysResult
Tab / Shift+TabMoves focus into and out of the group.
Arrow keysNative radio behavior: moves to and selects the adjacent rating.
SpaceSelects the focused rating when none is checked.
Events
EventDescription
input / changeNative events from the checked radio.

Form behavior

Submits name=value for the checked symbol; unanswered submits nothing and fails required validation.

States

Symbol rating states
StateHow it is expressedPresentation
Unansweredno checked radioAll symbols neutral.
Selected:checkedOnly the chosen option takes the inverse surface. Preceding symbols are not filled.
Focus:focus-visible on the radioTwo-tone focus ring around the option.

Accessibility

Forma provides

  • Keeps the glyph out of the accessibility tree and relies on text for each option's name.
  • Provides 44px targets with a visible border, so symbols are distinguishable without color.
  • Uses Highlight/HighlightText for the selected option in forced-colors mode.

Your application supplies

  • Write screen-reader text for every option that includes its position and meaning.
  • Add a visible key when the glyphs are not a widely understood convention.
  • Do not add application styling that fills all symbols up to the selection without also keeping the chosen one distinct.

Responsive behavior

  • Options wrap within an inline flex row capped at 100% width.
  • Targets keep their 44px minimum at every width; long scales take more lines rather than shrinking.
  • There are no breakpoints.

Motion

  • Background, border and text color of an option use the shared perceptual interpolation (about 120ms) when selected. Selection is immediate and timing is identical for every value.
  • Under prefers-reduced-motion: reduce the foundation makes these transitions effectively instant.

Usage guidance

Do

  • Keep scales short, typically five positions.
  • Use the same glyph for every position on a star scale so only position carries meaning.

Avoid

  • Using the glyph (or its count) as the only communication of meaning.
  • Using a symbol rating for a displayed average; that is text, not a control.

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.