el-schneider/statamic-choices

Card-style choice fieldtype for Statamic

v0.1.1 2026-05-09 21:32 UTC

Requires

• statamic/cms: ^5.0 || ^6.0

Requires (Dev)

• laravel/pint: ^1.14
• orchestra/testbench: ^10.0
• pestphp/pest: ^4.0

MIT

• Jonas List

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

Setting	Values	Default	Description
mode	single, multiple	single	Whether the field behaves like radios or checkboxes.
variant	content, image	content	Content cards show labels/text. Image cards use full-bleed images.
card_width	100, 50, 33, 25, 20	100	Approximate card width before wrapping.
image_aspect	1/1, 4/3, 16/9	1/1	Image card aspect ratio. Only used by variant: image.
default	scalar or YAML array	—	Default selected value(s).

Option settings

Setting	Description
value	Stored value. Must be unique.
label	Human-readable label shown in the control panel and augmented output. Falls back to value.
image	Optional Statamic asset. Use normal asset IDs like assets::cards/basic.svg.
description	Optional supporting text for content cards.
use_html	Enables trusted custom HTML for content cards. When enabled, HTML replaces image and description.
html	Trusted HTML rendered inside the card. No Antlers rendering.

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