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>- Category
- Selection and 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: coverand 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.
Minimal image choice
Rendered from the canonical pattern file.
<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
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.
<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.
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.
<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.
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.
What changes at narrow widths
- At 44rem and below
forma-choice--mediaswitches 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.
<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.
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 | checkbox | — | Radio for one answer, checkbox for several. The media variant draws no indicator for either. |
name | input | string | — | Shared by the options of one question; unique per question on the page. |
value | input | string | "on" | Submitted value for each chosen option. |
checked | input | boolean | absent | Initial selection. |
required | input | boolean | absent | Native constraint for radio groups. |
disabled | input | boolean | absent | Makes an option unavailable and dims the whole card. |
alt | img | "" 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-hidden | inline svg | true | — | Hides decorative inline SVG previews from assistive technology. |
| Hook | Kind | Values or default | Description |
|---|---|---|---|
.forma-choice--media | Modifier 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__media | Element 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__content | Element class | — | The bold option name and supporting text, as in every choice card. |
| Keys | Result |
|---|---|
| Tab / Shift+Tab | Radios: the group is one tab stop. Checkboxes: each option is a tab stop. |
| Arrow keys | Radios only: move to and select the next or previous option (native behavior). |
| Space | Toggles a checkbox, or selects the focused radio when none is selected. |
| Event | Description |
|---|---|
input / change | Native 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
| State | How it is expressed | Presentation |
|---|---|---|
| Unselected | no checked attribute | Functional border, primary surface, no indicator. |
| Selected | :checked | Accent 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 input | Two-tone focus ring around the whole card. |
| Disabled | disabled attribute | Card 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: reducethe 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.