Download the PHP package daikazu/filament-image-checkbox-group without Composer

Filament Image Checkbox Group

A custom form component for FilamentPHP that displays checkbox group options as image-based selectable buttons.

Requirements

• PHP 8.3+
• Laravel 12 or 13
• Filament v4 or v5

Features

• Styled as buttons instead of traditional checkboxes
• Contains an image and an optional label for each option
• Allows multiple selections
• Supports min and max selection constraints
• Optional requirement validation with min/max enforcement
• Emits selected values to Livewire as an array
• Styled options as cards with hover/active states
• Prevents selecting more than max items
• Compact label mode for text-only button styling
• Image preview popover on hover (in compact mode)
• Reusable as a custom form field
• Full keyboard accessibility support (WCAG 2.1 AA compliant)
• Respects prefers-reduced-motion for users with vestibular disorders

Installation

You can install the package via composer:

Styling Configuration

if you don't have a theme already, you need to create one. check the Filament theme docs for your version: v5 / v4

after you're done, add the following to your resources/filament/admin/theme.css (depending on your panel)

finally, run

You can publish the config file with:

Optionally, you can publish the views using:

Usage

Grid Columns Configuration

The component supports two ways to configure the grid layout:

1. Simple integer configuration:

2. Detailed responsive configuration:

The responsive configuration supports these breakpoints:

• default: Mobile first (< 640px)
• sm: Small screens (≥ 640px)
• md: Medium screens (≥ 768px)
• lg: Large screens (≥ 1024px)
• xl: Extra large screens (≥ 1280px)
• 2xl: 2XL screens (≥ 1536px)

You can specify any combination of breakpoints. Unspecified breakpoints will inherit from the previous breakpoint:

With Min/Max Selection

Without Images (Label-only buttons)

Compact Labels Layout

Use compactLabels() to display options as compact text buttons instead of square image cards. This is useful when you want a more traditional button-group appearance, or when images are optional supplementary content rather than the primary visual.

Behavior differences with compactLabels():

With images and compact labels (popover preview):

When options have images but compactLabels() is enabled, the images appear as a popover preview on hover and focus. The popover automatically positions itself based on available screen space (top, bottom, left, or right).

Optional Selection

Configuration

You can configure default behavior for all instances of this component:

Customization

Helper Text

Add helper text to guide users:

Validation

The component handles validation automatically:

• If the field is marked as ->required(), it will require at least 1 selection (or the number specified by ->minSelect())
• If ->maxSelect() is set, it will enforce a maximum number of selections
• If the field is not required, no minimum selection validation is applied, but the max limit is still enforced

Data Format

The component stores an array of selected values in your model:

Examples

Property Amenities Selection

Testing

Changelog

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

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

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

Credits

• Mike Wall
• All Contributors

License

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