Ranking
<forma-ranking>
Ordered-choice presentation with non-drag movement controls and visible positions.
- Authoring tag
<forma-ranking>- Category
- Assessment and survey
- Behavior owner
- Application / Limen
- Canonical source
patterns/ranking.html
Purpose
Ranking shows items in an ordered list with a visible position number and Move up / Move down buttons on each row. Forma supplies the visual contract only: the list, the position badges, 44px move buttons, and a visually hidden live region for announcements. The application (Limen) owns reordering: it moves the item in the DOM, renumbers positions, disables moves that are not possible at the ends, keeps focus on the moved control, and writes an announcement. Drag-and-drop may be layered on, but the buttons must always remain.
Use when
- Users must put every item in a complete order of preference or priority.
- The list is short enough to reorder with buttons (typically up to about eight items).
- A keyboard- and touch-operable path to reorder is required, with or without drag.
Avoid when
- Only the top and bottom matter: use Best–Worst.
- Items are rated independently: use Single-choice matrix or Ordinal scale.
- Relative weight matters, not just order: use Allocation.
- The list is long or items move between groups: use Lane board or an application-specific tool.
Behavior to know
- An ordered list (
ol), so position is also conveyed by list semantics. - Position badges are
aria-hidden; each button's name states the item and direction. - Move buttons are native
button type="button"elements at least 44 by 44px. - The announcement paragraph is visually hidden but remains in the accessibility tree as a polite live region.
Basic example
The smallest correct markup: the canonical pattern from patterns/ranking.html inside its public tag. Copy this first, then adapt labels, names and state.
Minimal ranking
Rendered from the canonical pattern file.
Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.
<forma-ranking class="forma-component-tag">
<fieldset class="forma-ranking">
<legend class="forma-ranking__legend">Rank the priorities from most to least important.</legend>
<p class="forma-field__description">Use the move controls to change the order. Drag-and-drop may be added only as an optional Limen enhancement.</p>
<ol class="forma-ranking__list">
<li class="forma-ranking__item" data-forma-rank="1">
<span class="forma-ranking__position" aria-hidden="true">1</span>
<span class="forma-ranking__label">Reliability</span>
<span class="forma-ranking__actions">
<button type="button" disabled aria-label="Move Reliability up">↑</button>
<button type="button" aria-label="Move Reliability down">↓</button>
</span>
</li>
<li class="forma-ranking__item" data-forma-rank="2">
<span class="forma-ranking__position" aria-hidden="true">2</span>
<span class="forma-ranking__label">Delivery speed</span>
<span class="forma-ranking__actions">
<button type="button" aria-label="Move Delivery speed up">↑</button>
<button type="button" aria-label="Move Delivery speed down">↓</button>
</span>
</li>
<li class="forma-ranking__item" data-forma-rank="3">
<span class="forma-ranking__position" aria-hidden="true">3</span>
<span class="forma-ranking__label">Cost efficiency</span>
<span class="forma-ranking__actions">
<button type="button" aria-label="Move Cost efficiency up">↑</button>
<button type="button" disabled aria-label="Move Cost efficiency down">↓</button>
</span>
</li>
</ol>
<p class="forma-ranking__announcement" aria-live="polite" aria-atomic="true"></p>
</fieldset>
</forma-ranking>
Click or tap the code once to select all of it, then copy.
Examples
After moving an item up
Delivery speed has just been moved to first place with its Move up button. The application renumbered the list, disabled the impossible moves at the ends and wrote the announcement.
Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.
<forma-ranking class="forma-component-tag">
<fieldset class="forma-ranking">
<legend class="forma-ranking__legend">Rank these goals for the next release.</legend>
<ol class="forma-ranking__list">
<li class="forma-ranking__item" data-forma-rank="1">
<span class="forma-ranking__position" aria-hidden="true">1</span>
<span class="forma-ranking__label">Delivery speed</span>
<span class="forma-ranking__actions">
<button type="button" disabled aria-label="Move Delivery speed up">↑</button>
<button type="button" aria-label="Move Delivery speed down">↓</button>
</span>
</li>
<li class="forma-ranking__item" data-forma-rank="2">
<span class="forma-ranking__position" aria-hidden="true">2</span>
<span class="forma-ranking__label">Reliability</span>
<span class="forma-ranking__actions">
<button type="button" aria-label="Move Reliability up">↑</button>
<button type="button" aria-label="Move Reliability down">↓</button>
</span>
</li>
<li class="forma-ranking__item" data-forma-rank="3">
<span class="forma-ranking__position" aria-hidden="true">3</span>
<span class="forma-ranking__label">Accessibility fixes</span>
<span class="forma-ranking__actions">
<button type="button" aria-label="Move Accessibility fixes up">↑</button>
<button type="button" aria-label="Move Accessibility fixes down">↓</button>
</span>
</li>
<li class="forma-ranking__item" data-forma-rank="4">
<span class="forma-ranking__position" aria-hidden="true">4</span>
<span class="forma-ranking__label">Cost efficiency</span>
<span class="forma-ranking__actions">
<button type="button" aria-label="Move Cost efficiency up">↑</button>
<button type="button" disabled aria-label="Move Cost efficiency down">↓</button>
</span>
</li>
</ol>
<p class="forma-ranking__announcement" aria-live="polite" aria-atomic="true">Delivery speed moved to position 1 of 4.</p>
</fieldset>
</forma-ranking>
Click or tap the code once to select all of it, then copy.
Long item labels with heavy motion weight
Items with sentence-length labels that wrap within the middle column. Heavy motion weight gives any application-driven settle (via the reorder hooks) a slower, more damped feel; it does not change the order logic.
Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.
<forma-ranking class="forma-component-tag">
<fieldset class="forma-ranking" data-forma-motion-weight="heavy" aria-describedby="ranking-long-help">
<legend class="forma-ranking__legend">Order the risks from most to least urgent.</legend>
<p class="forma-field__description" id="ranking-long-help">Use the arrow buttons to move a risk. The top item is the most urgent.</p>
<ol class="forma-ranking__list">
<li class="forma-ranking__item" data-forma-rank="1">
<span class="forma-ranking__position" aria-hidden="true">1</span>
<span class="forma-ranking__label">Customer data exports are not encrypted when written to the shared archive bucket</span>
<span class="forma-ranking__actions">
<button type="button" disabled aria-label="Move unencrypted exports up">↑</button>
<button type="button" aria-label="Move unencrypted exports down">↓</button>
</span>
</li>
<li class="forma-ranking__item" data-forma-rank="2">
<span class="forma-ranking__position" aria-hidden="true">2</span>
<span class="forma-ranking__label">The primary database has no tested failover to the secondary region</span>
<span class="forma-ranking__actions">
<button type="button" aria-label="Move untested failover up">↑</button>
<button type="button" disabled aria-label="Move untested failover down">↓</button>
</span>
</li>
</ol>
<p class="forma-ranking__announcement" aria-live="polite" aria-atomic="true"></p>
</fieldset>
</forma-ranking>
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.
Ranking on a phone
Below 44rem the move buttons drop under the item text and split the row width, giving large touch targets.
Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.
What changes at narrow widths
- Each row becomes a two-column grid (position, label); the actions move to their own full-width line beneath.
- The two move buttons share that line equally, each at least 44px tall, which suits thumbs better than two small squares.
- Labels wrap; the list never scrolls horizontally at 320px.
- Reordering remains button-driven; any drag enhancement must not be the only path on touch devices.
<forma-ranking class="forma-component-tag">
<fieldset class="forma-ranking">
<legend class="forma-ranking__legend">Rank your preferred working hours.</legend>
<ol class="forma-ranking__list">
<li class="forma-ranking__item" data-forma-rank="1">
<span class="forma-ranking__position" aria-hidden="true">1</span>
<span class="forma-ranking__label">Early (7:00 to 15:00)</span>
<span class="forma-ranking__actions">
<button type="button" disabled aria-label="Move Early up">↑</button>
<button type="button" aria-label="Move Early down">↓</button>
</span>
</li>
<li class="forma-ranking__item" data-forma-rank="2">
<span class="forma-ranking__position" aria-hidden="true">2</span>
<span class="forma-ranking__label">Standard (9:00 to 17:00)</span>
<span class="forma-ranking__actions">
<button type="button" aria-label="Move Standard up">↑</button>
<button type="button" aria-label="Move Standard down">↓</button>
</span>
</li>
<li class="forma-ranking__item" data-forma-rank="3">
<span class="forma-ranking__position" aria-hidden="true">3</span>
<span class="forma-ranking__label">Late (11:00 to 19:00)</span>
<span class="forma-ranking__actions">
<button type="button" aria-label="Move Late up">↑</button>
<button type="button" disabled aria-label="Move Late down">↓</button>
</span>
</li>
</ol>
<p class="forma-ranking__announcement" aria-live="polite" aria-atomic="true"></p>
</fieldset>
</forma-ranking>
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.
Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.
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 | button | button | — | Required so move buttons never submit the surrounding form. |
aria-label | button | "Move <item> up" / "Move <item> down" | — | Required. The arrow glyph is not a name; the label states item and direction. |
disabled | button | boolean | absent | Set by the application on Move up for the first item and Move down for the last. |
aria-hidden | .forma-ranking__position | true | — | The badge is visual; list semantics and announcements carry position. |
aria-live | .forma-ranking__announcement | polite | — | Announces the application's movement messages. |
aria-atomic | .forma-ranking__announcement | true | — | Reads the whole message each time it changes. |
data-forma-rank | .forma-ranking__item | integer | — | Authoritative position written by the application for its own use. Forma does not style it. |
aria-describedby | fieldset | id list | — | Associates instructions with the ranking. |
| Hook | Kind | Values or default | Description |
|---|---|---|---|
.forma-ranking | Block class | — | Root fieldset with browser border and padding removed; also a motion scope for reorder settling. |
.forma-ranking__actions | Element class | — | Container for the move buttons; each button is at least 44 by 44px. |
.forma-ranking__announcement | Element class | — | Visually hidden live region for movement messages. |
.forma-ranking__item | Element class | — | Bordered row: position, label and actions. At least 3.25rem tall. |
.forma-ranking__label | Element class | — | Item text; wraps anywhere. |
.forma-ranking__legend | Element class | — | Question text. |
.forma-ranking__list | Element class | — | Unstyled ordered list stacking the items with a small gap. |
.forma-ranking__position | Element class | — | Inverse square badge showing the current position number. |
[data-forma-motion-weight] | Attribute hook | "heavy", "light", "standard" | Presentation-only perceived mass (light, standard, heavy) for application-driven settle transitions such as data-forma-manipulation on items. Never encodes importance. |
| Keys | Result |
|---|---|
| Tab / Shift+Tab | Moves through the enabled move buttons in order; disabled buttons are skipped. |
| Enter / Space | Activates the focused move button (native button behavior). The application performs the move and should keep focus on the moved item's corresponding button. |
| Event | Description |
|---|---|
click | Native click from a move button. Limen handles it to reorder, renumber and announce. |
Form behavior
The list does not submit anything natively. The application serialises the order, for example into hidden inputs, or sends it directly.
States
| State | How it is expressed | Presentation |
|---|---|---|
| Ordered | DOM order plus data-forma-rank | Position badges show 1 to n in list order. |
| End of list | disabled on the first Move up and last Move down | Impossible moves are disabled and skipped by focus. |
| Announced | text in .forma-ranking__announcement | Screen readers hear the movement result. |
| Dragging / drop feedback | data-forma-manipulation and data-forma-drop on items (application-set) | Optional direct-manipulation presentation documented in Reorder states. |
Accessibility
Forma provides
- Provides 44px native buttons as the non-drag reorder path.
- Places a polite, atomic live region in the structure, visually hidden but announced.
- Uses an ordered list so position is conveyed without the badge.
- Draws item borders in CanvasText under forced colors.
Your application supplies
- Implement the move, renumber badges and data-forma-rank, and disable moves at the ends.
- Keep focus on the moved item's button after a move, and write an announcement such as "Reliability moved to position 2 of 4."
- Label every button with item and direction.
- Never make drag the only way to reorder.
Responsive behavior
- Wide:
auto minmax(0, 1fr) autocolumns for position, label and actions. - Below 44rem: actions move to a full-width second line and split into two equal buttons.
- Labels wrap anywhere; no horizontal overflow.
Motion
- Items do not animate on their own. When the application sets
data-forma-manipulationon an item, its translate follows the pointer with no lag while dragging and settles with a damped, non-overshooting transition afterwards;data-forma-motion-weighton the ranking sets that settle duration. - Button hover and press use the foundation's perceptual background interpolation.
- Under
prefers-reduced-motion: reducesettle transitions are effectively instant and items appear at their final position.
Motion weights
Forma motion is physics-derived: perceived mass changes how a surface accelerates and settles, never what state it is in. Compare the three presentation weights of the same markup:
Usage guidance
Do
- Start from a neutral or randomised order when order bias matters.
- Announce each move with the item and its new position.
Avoid
- Relying on drag-and-drop only.
- Using motion weight to suggest which item matters most.
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.