README

Statamic Choices

Help editors make better decisions. Turn radios and checkboxes into visual choice cards.

A plain radio group asks editors to pick a word. Choices lets you show what they're actually picking — an image, a description, or trusted custom HTML when words won't cut it.

Features

• Single or multiple: Behaves like radios or checkboxes
• Rich cards: Label, image, description, or some fine custom HTML per option
• Two variants: Content cards for text-led choices, image cards when the picture is the choice
• Frontend-ready: Augments to full option objects with resolved assets

Requirements

• Statamic 5 or 6
• PHP 8.3+

Installation

composer require el-schneider/statamic-choices

Usage

Add a Choices field to your blueprint and configure the available options.

Single choice

plan:
  type: choices
  display: Plan
  mode: single
  card_width: 50
  variant: content
  options:
    - value: basic
      label: Basic
      image: assets::cards/basic.svg
      description: Simple publishing workflow for small teams.
    - value: pro
      label: Pro
      image: assets::cards/pro.svg
      description: More automation and editorial flexibility.
      use_html: true
      html:
        code: '<span class="badge-sm">Popular</span>'
    - value: enterprise
      label: Enterprise
      image: assets::cards/enterprise.svg
      description: Advanced controls for large organizations.

Saved value:

plan: pro

Multiple choices

addons:
  type: choices
  display: Add-ons
  mode: multiple
  card_width: 33
  variant: content
  options:
    - value: analytics
      label: Analytics
      image: assets::cards/analytics.svg
      description: Include dashboard and conversion reporting.
    - value: support
      label: Priority support
      image: assets::cards/support.svg
      description: Faster response times from the support team.

Saved value:

addons:
  - analytics
  - support

Configuration Reference

Field settings

Option settings

Custom HTML

Content cards can swap their image and description for trusted custom HTML. Intended for blueprint configuration — not editor input. No Antlers.

options:
  - value: pro
    label: Pro
    use_html: true
    html:
      code: '<span class="badge-sm">Popular</span>'

Labels and selection controls stay under fieldtype control.

Image Cards

Image cards are useful for visual presets, colorways, layouts, or other choices where the image is the interface.

layout:
  type: choices
  mode: single
  variant: image
  card_width: 25
  image_aspect: 4/3
  options:
    - value: editorial
      label: Editorial
      image: assets::layouts/editorial.jpg
    - value: portfolio
      label: Portfolio
      image: assets::layouts/portfolio.jpg

In image mode, labels are used for tooltips and accessible names. Descriptions and custom HTML are ignored.

Frontend Usage

The field stores only selected values. When augmented, it returns the selected option data.

Single mode

{{ plan }}
  <h2>{{ label }}</h2>
  {{ if image }}<img src="{{ image:url }}" alt="{{ image:alt }}">{{ /if }}
  {{ if description }}<p>{{ description }}</p>{{ /if }}
{{ /plan }}

Augmented shape:

[
    'value' => 'pro',
    'label' => 'Pro',
    'use_html' => false,
    'image' => Statamic\Contracts\Assets\Asset::class,
    'description' => 'More automation and editorial flexibility.',
    'html' => null,
]

Multiple mode

{{ addons }}
  <div class="addon-card">
    <h3>{{ label }}</h3>
    {{ if image }}<img src="{{ image:url }}" alt="{{ image:alt }}">{{ /if }}
    {{ if description }}<p>{{ description }}</p>{{ /if }}
  </div>
{{ /addons }}

Multiple selections are returned in the option order from the blueprint.

Notes

• Unknown saved values are ignored.
• Unprefixed image paths only resolve when exactly one asset container is configured. Prefer explicit IDs like assets::path/to/image.svg.

Development

npm run build
./vendor/bin/pest
./vendor/bin/pint --test
npm run format:check

License

MIT