Symbol rating
<forma-symbol-rating>
Ordinal rating presented with symbols while retaining accessible textual labels.
- Authoring tag
<forma-symbol-rating>- Category
- Assessment and survey
- 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-onlytext, 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.
Minimal symbol rating
Rendered from the canonical pattern file.
<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
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".
<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.
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.
<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.
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.
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.
<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.
Mobile · 320px
The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.
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.
| Attribute | On | Values | Default | Description |
|---|---|---|---|---|
type | input | radio | — | Required. One radio per symbol. |
name | input | string | — | Groups the symbols into one answer. Unique per question. |
value | input | string | — | Submitted rating. Meaning and scoring stay in the application. |
required | first input | boolean | absent | Native required-group validation. |
checked | input | boolean | absent | Restores a saved rating. |
aria-hidden | .forma-symbol-rating__symbol | true | — | Required. The glyph is decorative and must not be the accessible name. |
aria-describedby | fieldset | id list | — | Associates a key or help text with the rating. |
| Hook | Kind | Values or default | Description |
|---|---|---|---|
.forma-symbol-rating | Block class | — | Root fieldset with browser border and padding removed. |
.forma-symbol-rating__legend | Element class | — | Question text. |
.forma-symbol-rating__option | Element class | — | Bordered square label, at least 44px each way. The radio inside is visually hidden. |
.forma-symbol-rating__options | Element class | — | Wrapping inline flex row of options with a 0.25rem gap. |
.forma-symbol-rating__symbol | Element class | — | The decorative glyph at 1.35rem. |
.forma-sr-only | Block class | — | Visually hidden text that gives each option its accessible name, such as "3 of 5, neutral". |
| Keys | Result |
|---|---|
| Tab / Shift+Tab | Moves focus into and out of the group. |
| Arrow keys | Native radio behavior: moves to and selects the adjacent rating. |
| Space | Selects the focused rating when none is checked. |
| Event | Description |
|---|---|
input / change | Native events from the checked radio. |
Form behavior
Submits name=value for the checked symbol; unanswered submits nothing and fails required validation.
States
| State | How it is expressed | Presentation |
|---|---|---|
| Unanswered | no checked radio | All symbols neutral. |
| Selected | :checked | Only the chosen option takes the inverse surface. Preceding symbols are not filled. |
| Focus | :focus-visible on the radio | Two-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: reducethe 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.