Download the PHP package syriable/filament-choice-fields without Composer

Filament Choice Fields

Filament Choice Fields adds eight rich selection fields to FilamentPHP. Four are single-choice fields based on Radio, and four are multiple-choice fields based on CheckboxList. On top of the familiar options() / descriptions() API they add card, stacked-card and table layouts, per-option icons and badges, rich HTML "extras", state-aware descriptions, and a scrollable options list.

Requirements

• PHP 8.1+
• Filament 4 or 5

Installation

1. Install the package via Composer:

2. Make sure you have a custom Filament theme. Then register the package's Blade views as a Tailwind source in your theme's CSS file so the utility classes are compiled:

3. Rebuild your assets so the theme picks up the new classes:

Components

All fields live in the Syriable\Filament\Plugins\Translations\ChoiceFields\Filament\Forms\Components namespace. Import the ones you need:

CheckboxList

Vertical list layout with descriptions and extras for multiple selections.

CheckboxCard

Card-based layout with descriptions and extras for multiple selections.

CheckboxStackedCard

Stacked card layout with descriptions and extras for multiple selections.

CheckboxTable

Responsive table layout with descriptions for multiple selections.

RadioList

Vertical list layout with descriptions.

RadioCard

Card-based layout with descriptions and extras.

RadioStackedCard

Stacked card layout with descriptions and extras.

RadioTable

Responsive table layout with descriptions.

Single-option checkbox

Unlike the eight fields above (which present many options), SingleCheckboxCard is a single boolean field — a styled wrapper around Filament's Filament\Forms\Components\Checkbox. It stores true/false and renders one card whose title is the field's label(). It reuses the same styling system as the list-based fields (icon, badge, color, description, extra, hidden inputs), but the content methods are single values rather than arrays keyed by option value.

The available methods mirror the list-based fields, in singular form:

List style

SingleCheckboxList is the flat list-row counterpart to SingleCheckboxCard — a compact, low-elevation row instead of an elevated card. It exposes the exact same single-value API, so you can switch styles by changing the class name:

The only behavioural difference: when you hide the native control with hiddenInputs(), the list style highlights the checked row with a background tint rather than the card's check icon, so it does not use hiddenInputIcon().

More single-option styles will follow the same Single* naming. Note that StackedCard is intentionally not offered for single options — stacking is a multi-item effect and would render identically to a plain card.

Search, bulk actions, and disabling options

These behaviours are inherited unchanged from FilamentPHP's Radio and CheckboxList APIs.

Search:

Bulk select (checkbox-style fields only):

Disable a single option:

Enum support

Pass a backed enum class name to options() instead of an array. The enum can implement Filament's contracts to provide its label and description:

• Filament\Support\Contracts\HasLabel — the main label
• Filament\Support\Contracts\HasDescription — the subtitle

Use it in a schema:

To show extras for an enum, pass an extras([...]) array keyed by the enum value. If a case implements getColor(), supported layouts tint that option (the same behaviour as core FilamentPHP enums).

Customization

Field color

Selected descriptions

selectedDescriptions() shows a different description while an option is selected. Keyed by option value just like descriptions(), it renders the default text when the option is unchecked and swaps to the selected text once it is checked. The swap happens instantly in the browser (via a group-has-checked: CSS variant) with no extra server round-trip.

Each value accepts string | Htmlable, and the method also accepts an Arrayable or a Closure. An option that only defines a selected description shows nothing until it is selected.

Option icons

Add an icon next to each option's label, keyed by the option value. Use iconPosition() to place the icon before (default) or after the label.

Dynamic option icons

When the icon depends on the option value, use optionHasIcon() with a closure instead of building an icons() array. It receives the option $value (and $label) and returns an icon name, enum, or null. It takes precedence over icons() and still respects iconPosition().

Option badges

optionHasBadge() renders one or more badges next to an option's label. Return a single value, or an array to show multiple badges. Each value may be a string, Htmlable, or Closure; null/blank values are skipped. The closure receives the option $value (and $label).

Use string keys to render multiple badges and to target them from optionBadgeColor(). Because colors are keyed by the badge key (not its rendered label), the badge text itself may be a translation or a dynamic string:

optionBadgeColor() also accepts a plain string or closure that returns a single color applied to every badge. optionBadgeIcon() adds an icon to the badges. Unmatched badges fall back to the gray color.

Scrollable options (max height)

maxHeight() constrains the height of the options list and makes only the options scroll — the search field and bulk-action buttons stay fixed. It accepts any CSS length string (or a closure).

Hide native inputs on cards

Hidden input icon

By default, the hidden input icon for card components is heroicon-s-check-circle. You can override it:

visibleInputs() reverses hiddenInputs() (shows the native control again).

Rich extras (HTML)

Each extras() value accepts string | Htmlable | Closure | null. Plain strings are HTML-escaped, so they are safe by default. To render rich markup, pass an Htmlable (for example via str()->toHtmlString() or new HtmlString(...)); values may also be closures, which are resolved per option at render time.

Security: only wrap trusted, developer-authored markup in Htmlable. Rendering user- or database-supplied content as raw HTML exposes the form to XSS. Escape any dynamic value with e() before adding it to an Htmlable extra.

Testing

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Contributions and pull requests are always welcome. Please run composer lint and composer test before opening a PR to help keep CI green. See CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• syriable
• All Contributors

License

The MIT License (MIT). Please see License File for more information.