Skip to main content
ChoiceCards ← Back to Table of Contents

​
Summary

Premium single-select card group (radio behavior). Ideal for pricing plans, delivery methods, and feature selection. Supports rich option metadata (descriptions, prices, icons, badges) and multiple responsive layouts.
ClassBjanczak\FilamentFlexFields\Filament\Forms\Components\ChoiceCards
State typestring|int|null — one option key
Model cast'plan' => 'string' · 'type' => 'integer'
FieldTypechoice_cards
Playgroundchoice-cards slug in Flex Fields playground

​
Basic usage

​
Pricing plans (Stack layout)

use Bjanczak\FilamentFlexFields\Filament\Forms\Components\ChoiceCards;

ChoiceCards::make('plan')
    ->options([
        'starter' => [
            'label' => 'Starter',
            'description' => 'For individuals',
            'price' => '$5',
            'price_suffix' => '/mo',
        ],
        'pro' => [
            'label' => 'Pro',
            'description' => 'For teams',
            'price' => '$15',
            'price_suffix' => '/mo',
        ],
    ])
    ->default('pro');

​
Delivery methods (Media layout)

ChoiceCards::make('delivery')
    ->layout('media')
    ->gridColumns(['default' => 1, 'sm' => 3])
    ->options([
        'standard' => ['label' => 'Standard', 'icon' => 'heroicon-o-truck'],
        'express' => ['label' => 'Express', 'icon' => 'heroicon-o-bolt'],
        'rocket' => ['label' => 'Rocket', 'icon' => 'heroicon-o-rocket'],
    ]);

​
State & validation

​
Stored value

State is the option key from options(). 
$record->plan; // string|null — e.g. 'pro'

​
Validation rules (built-in)

RuleWhen
nullableAlways (unless required())
Rule::in(...)Value must match a configured option key
requiredWhen ->required()

​
Configuration API

All methods accept Closure unless noted.
MethodTypeDefaultDescription
options(array|Closure $options)Setup[]Rich option map. Keys: label, description, price, price_suffix, icon, badge, badge_color, disabled.
disabledOptions(array|Closure $keys)Setup[]Keys that cannot be selected.
layout(string|Closure $layout)Setup'stack'stack, grid, media, featured.
gridColumns(int|array|Closure $cols)Setup1Responsive columns for grid/media (max 4).
indicator(string|Closure|null $type)SetupautoSelection marker: radio, check, none.
variant(string|Closure $variant)Setup'default'default, primary (stronger selection), secondary.
color(string|Closure|null $color)Setup'primary'Accent color for selection borders/indicators.
size(string|Closure $size)Setup'md'Padding and typography scale: sm, md, lg.
ripple(bool|Closure $on)SetupfalseEnable Material-style click ripple.

​
Real-world examples

ChoiceCards::make('tier')
    ->layout('featured')
    ->variant('primary')
    ->indicator('check')
    ->options([
        'basic' => ['label' => 'Basic', 'price' => '$0'],
        'pro' => [
            'label' => 'Pro', 
            'price' => '$29', 
            'badge' => 'Recommended',
            'badge_color' => 'success'
        ],
    ]);

​
Payment method selector

ChoiceCards::make('payment_method')
    ->layout('media')
    ->gridColumns(2)
    ->options([
        'visa' => ['label' => '**** 1234', 'icon' => 'heroicon-o-credit-card'],
        'paypal' => ['label' => 'PayPal', 'icon' => 'heroicon-o-circle-stack'],
    ]);

​
Playground

/admin/flex-fields-playground/choice-cards See Playground for setup.
ComponentWhen to use instead
ChoiceCheckboxCardsFor multi-select card groups.
FlexChecklistFor a more compact multi-select list.
ItemCardGroupFor grouping rows that aren’t necessarily selectable form fields.

​
CSS classes (reference)

ClassRole
fff-choice-cardsRoot wrapper
fff-choice-cards--layout-{stack|grid|media|featured}Layout modifier
fff-choice-cards--variant-{default|primary|secondary}Visual variant
fff-choice-cards--{sm|md|lg}Size modifier
fff-choice-cardIndividual card element
fff-choice-card--selectedActive card state
fff-choice-card--disabledDisabled card state
fff-choice-card__indicatorSelection marker wrapper
fff-choice-card__rippleRipple animation element