Selection and choice

Image choice

<forma-image-choice>

Choice cards that pair media with visible text while keeping the native radio or checkbox as the input.

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

Purpose

Image choice is the Choice group card with a picture. Adding forma-choice--media to an forma-choice label turns it into a two-column card: an forma-choice__media frame with a 4:3 aspect ratio beside the usual bold label and supporting text. The input stays a native radio (single choice) or checkbox (several choices), so selection, keyboard behavior and form submission are unchanged. The image supports recognition; the visible text is the accessible name and must carry the whole meaning, because images never replace text.

Use when

  • Options are visual (layouts, themes, chart types, product variants) and a preview helps people recognise them.
  • Each option still has a clear text name that works without the image.
  • Two to about six options are compared in a list.

Avoid when

  • The picture is decoration with no recognition value: use a plain Choice group.
  • The meaning lives only in the image (for example a color swatch with no name): add a text name first, or reconsider the question.
  • There are many options that users filter or search: use Select or Combobox.

Behavior to know

  • Media frame and text sit side by side above 44rem and stack (media on top) at 44rem and below.
  • The drawn round/square indicator of the plain choice card is hidden in the media variant.
  • The selected card is shown by an accent border and a secondary surface; forced-colors mode fills it with Highlight.
  • Images are cropped to the frame with object-fit: cover and never widen the card.

Basic example

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

Canonical

Minimal image choice

Rendered from the canonical pattern file.

Which layout is easiest to scan?
HTML · Minimal image choice Raw HTML for HTML · Minimal image choice
<forma-image-choice class="forma-component-tag">
<fieldset class="forma-choice-group">
  <legend class="forma-choice-group__legend">Which layout is easiest to scan?</legend>

  <label class="forma-choice forma-choice--media">
    <input type="radio" name="layout-choice" value="compact" required>
    <span class="forma-choice__media">
      <img width="160" height="90" src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 160 90'%3E%3Crect width='160' height='90' fill='%23e3e0d7'/%3E%3Crect x='10' y='10' width='140' height='8' fill='%23686d68'/%3E%3Crect x='10' y='21' width='140' height='8' fill='%23686d68'/%3E%3Crect x='10' y='32' width='140' height='8' fill='%23686d68'/%3E%3Crect x='10' y='43' width='140' height='8' fill='%23686d68'/%3E%3Crect x='10' y='54' width='140' height='8' fill='%23686d68'/%3E%3Crect x='10' y='65' width='140' height='8' fill='%23686d68'/%3E%3Crect x='10' y='76' width='140' height='8' fill='%23686d68'/%3E%3C/svg%3E" alt="">
    </span>
    <span class="forma-choice__content">
      <strong>Compact layout</strong>
      <span>Dense rows with minimal whitespace.</span>
    </span>
  </label>

  <label class="forma-choice forma-choice--media">
    <input type="radio" name="layout-choice" value="spacious">
    <span class="forma-choice__media">
      <img width="160" height="90" src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 160 90'%3E%3Crect width='160' height='90' fill='%23e3e0d7'/%3E%3Crect x='10' y='10' width='140' height='8' fill='%23686d68'/%3E%3Crect x='10' y='34' width='140' height='8' fill='%23686d68'/%3E%3Crect x='10' y='58' width='140' height='8' fill='%23686d68'/%3E%3C/svg%3E" alt="">
    </span>
    <span class="forma-choice__content">
      <strong>Spacious layout</strong>
      <span>More separation and larger grouping regions.</span>
    </span>
  </label>
</fieldset>
</forma-image-choice>

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

Examples

Scenario

Chart types, several allowed

Checkbox-backed media cards for a dashboard builder, with two chosen. The previews are inline SVG marked aria-hidden, so each option is announced only by its visible name and description.

Which charts should the dashboard include?
HTML · Chart types, several allowed Raw HTML for HTML · Chart types, several allowed
<forma-image-choice class="forma-component-tag">
  <fieldset class="forma-choice-group">
    <legend class="forma-choice-group__legend">Which charts should the dashboard include?</legend>
    <label class="forma-choice forma-choice--media">
      <input type="checkbox" name="image-choice-chart-type-checkboxes" value="line" checked>
      <span class="forma-choice__media">
        <svg viewBox="0 0 120 90" width="120" height="90" aria-hidden="true" focusable="false"><polyline points="10,70 40,45 65,55 110,20" fill="none" stroke="currentColor" stroke-width="4"/></svg>
      </span>
      <span class="forma-choice__content"><strong>Line chart</strong><span>Change over time for one or two measures.</span></span>
    </label>
    <label class="forma-choice forma-choice--media">
      <input type="checkbox" name="image-choice-chart-type-checkboxes" value="bar" checked>
      <span class="forma-choice__media">
        <svg viewBox="0 0 120 90" width="120" height="90" aria-hidden="true" focusable="false"><rect x="15" y="40" width="18" height="40" fill="currentColor"/><rect x="45" y="20" width="18" height="60" fill="currentColor"/><rect x="75" y="50" width="18" height="30" fill="currentColor"/></svg>
      </span>
      <span class="forma-choice__content"><strong>Bar chart</strong><span>Compare totals across categories.</span></span>
    </label>
    <label class="forma-choice forma-choice--media">
      <input type="checkbox" name="image-choice-chart-type-checkboxes" value="table">
      <span class="forma-choice__media">
        <svg viewBox="0 0 120 90" width="120" height="90" aria-hidden="true" focusable="false"><rect x="10" y="15" width="100" height="60" fill="none" stroke="currentColor" stroke-width="3"/><line x1="10" y1="35" x2="110" y2="35" stroke="currentColor" stroke-width="3"/><line x1="10" y1="55" x2="110" y2="55" stroke="currentColor" stroke-width="3"/><line x1="50" y1="15" x2="50" y2="75" stroke="currentColor" stroke-width="3"/></svg>
      </span>
      <span class="forma-choice__content"><strong>Table</strong><span>Exact values with sorting.</span></span>
    </label>
  </fieldset>
</forma-image-choice>

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

Scenario

Preselected theme with an unavailable option

A single-choice radio set with the current theme checked and one option natively disabled by the application. Because the media variant has no drawn indicator, the visible text ("Current theme") also states which option is active.

Workspace theme
HTML · Preselected theme with an unavailable option Raw HTML for HTML · Preselected theme with an unavailable option
<forma-image-choice class="forma-component-tag">
  <fieldset class="forma-choice-group">
    <legend class="forma-choice-group__legend">Workspace theme</legend>
    <label class="forma-choice forma-choice--media">
      <input type="radio" name="image-choice-theme-preselected" value="light" checked>
      <span class="forma-choice__media">
        <svg viewBox="0 0 120 90" width="120" height="90" aria-hidden="true" focusable="false"><rect x="8" y="8" width="104" height="74" fill="none" stroke="currentColor" stroke-width="3"/><rect x="8" y="8" width="30" height="74" fill="currentColor" opacity="0.2"/></svg>
      </span>
      <span class="forma-choice__content"><strong>Light</strong><span>Current theme. Dark text on a pale surface.</span></span>
    </label>
    <label class="forma-choice forma-choice--media">
      <input type="radio" name="image-choice-theme-preselected" value="dark">
      <span class="forma-choice__media">
        <svg viewBox="0 0 120 90" width="120" height="90" aria-hidden="true" focusable="false"><rect x="8" y="8" width="104" height="74" fill="currentColor"/></svg>
      </span>
      <span class="forma-choice__content"><strong>Dark</strong><span>Pale text on a dark surface.</span></span>
    </label>
    <label class="forma-choice forma-choice--media">
      <input type="radio" name="image-choice-theme-preselected" value="brand" disabled>
      <span class="forma-choice__media">
        <svg viewBox="0 0 120 90" width="120" height="90" aria-hidden="true" focusable="false"><circle cx="60" cy="45" r="28" fill="none" stroke="currentColor" stroke-width="3" stroke-dasharray="6 6"/></svg>
      </span>
      <span class="forma-choice__content"><strong>Organization brand</strong><span>Unavailable: your administrator has not published a brand yet.</span></span>
    </label>
  </fieldset>
</forma-image-choice>

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

Stacked media on a phone

Two layout previews at phone width. Each card stacks its media frame above the text so the preview keeps a usable size and the text keeps the full width.

Viewport width

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

What changes at narrow widths

  • At 44rem and below forma-choice--media switches to one column: the 4:3 media frame spans the card width above the label and description.
  • The whole card, image included, is the tap target for the radio.
  • Images scale to the frame (max-inline-size: 100%, object-fit: cover), so large source images cannot cause horizontal overflow at 320px.
  • Cards become taller in portrait; plan for the list to scroll vertically rather than shrinking previews.
HTML · Stacked media on a phone Raw HTML for HTML · Stacked media on a phone
<forma-image-choice class="forma-component-tag">
  <fieldset class="forma-choice-group">
    <legend class="forma-choice-group__legend">Which layout is easiest to scan?</legend>
    <label class="forma-choice forma-choice--media">
      <input type="radio" name="image-choice-mobile-stacked-media" value="list" required>
      <span class="forma-choice__media">
        <svg viewBox="0 0 120 90" width="120" height="90" aria-hidden="true" focusable="false"><rect x="10" y="12" width="100" height="14" fill="currentColor"/><rect x="10" y="38" width="100" height="14" fill="currentColor"/><rect x="10" y="64" width="100" height="14" fill="currentColor"/></svg>
      </span>
      <span class="forma-choice__content"><strong>List</strong><span>One item per row with the most detail.</span></span>
    </label>
    <label class="forma-choice forma-choice--media">
      <input type="radio" name="image-choice-mobile-stacked-media" value="grid">
      <span class="forma-choice__media">
        <svg viewBox="0 0 120 90" width="120" height="90" aria-hidden="true" focusable="false"><rect x="10" y="10" width="45" height="32" fill="currentColor"/><rect x="65" y="10" width="45" height="32" fill="currentColor"/><rect x="10" y="50" width="45" height="32" fill="currentColor"/><rect x="65" y="50" width="45" height="32" fill="currentColor"/></svg>
      </span>
      <span class="forma-choice__content"><strong>Grid</strong><span>Cards with a thumbnail and title.</span></span>
    </label>
  </fieldset>
</forma-image-choice>

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 | checkbox—Radio for one answer, checkbox for several. The media variant draws no indicator for either.
nameinputstring—Shared by the options of one question; unique per question on the page.
valueinputstring"on"Submitted value for each chosen option.
checkedinputbooleanabsentInitial selection.
requiredinputbooleanabsentNative constraint for radio groups.
disabledinputbooleanabsentMakes an option unavailable and dims the whole card.
altimg"" or text—Use alt="" when the visible text fully names the option, so the name is not announced twice. Give real alt text only when the image adds information the text does not.
aria-hiddeninline svgtrue—Hides decorative inline SVG previews from assistive technology.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-choice--mediaModifier class—Owned by Choice group. Turns an forma-choice card into the media layout: two columns, inline-start padding reduced, drawn indicator hidden. One column at 44rem and below.
.forma-choice__mediaElement class—The media frame: 4:3 aspect ratio, subtle border, secondary surface, content centred and clipped. A child img is scaled to fit with object-fit: cover.
.forma-choice__contentElement class—The bold option name and supporting text, as in every choice card.
Keyboard interaction
KeysResult
Tab / Shift+TabRadios: the group is one tab stop. Checkboxes: each option is a tab stop.
Arrow keysRadios only: move to and select the next or previous option (native behavior).
SpaceToggles a checkbox, or selects the focused radio when none is selected.
Events
EventDescription
input / changeNative events from the radio or checkbox. Forma adds none.

Form behavior

Identical to Choice group (radios) or Multi-choice (checkboxes): checked options submit name=value, required applies to radio groups, and reset restores initial state.

States

Image choice states
StateHow it is expressedPresentation
Unselectedno checked attributeFunctional border, primary surface, no indicator.
Selected:checkedAccent border and secondary surface. There is no shape indicator in this variant, so the change is a border and surface color change; forced-colors mode uses a Highlight fill.
Focus:focus-visible on the inputTwo-tone focus ring around the whole card.
Disableddisabled attributeCard at reduced opacity with a not-allowed cursor.

Accessibility

Forma provides

  • Keeps a native radio or checkbox inside the card, so the accessible name is the visible text and the state is programmatic.
  • Makes the whole card, including the media, the click and touch target.
  • Keeps the media inside a bounded frame so images cannot break layout at 320px or 400% zoom.
  • Uses Highlight/HighlightText for selected cards in forced-colors mode.

Your application supplies

  • Give every option a visible text name that works without the image.
  • Use alt="" or aria-hidden for previews that repeat the text, and real alt text only for information the text lacks.
  • Because the selected state has no shape cue in this variant, consider stating the current choice in text (as in "Current theme") where it matters.
  • Supply images at a 4:3 ratio, or accept cropping by object-fit: cover.

Responsive behavior

  • Above 44rem the card is a two-column grid: a minmax(5rem, 8rem) media column and a flexible text column.
  • At 44rem and below the card is one column with the media on top.
  • The media frame keeps a 4:3 aspect ratio and clips overflow; images scale down to fit.
  • Text wraps in its column; no horizontal overflow at 320px.

Motion

  • Border, background and text color change by perceptual interpolation (about 120ms), shared with every choice card; nothing moves and selection is immediate.
  • Images are not animated. Under prefers-reduced-motion: reduce the color transition is effectively instant.

Usage guidance

Do

  • Use previews that differ in structure, not only in color.
  • Keep option names short and put the distinguishing detail in the supporting text.

Avoid

  • Image-only options without a visible text name.
  • Photographs whose important detail disappears when cropped to 4:3 or shown at 8rem wide.
  • Mixing media and plain cards in the same question.

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.