> ## Documentation Index
> Fetch the complete documentation index at: https://filament-34a8cf01.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkbox list

> [!WARNING]
>
> You are currently viewing the documentation for Filament 4.x, which is a previous version of Filament.
>
> Looking for the current stable version? Visit the [5.x documentation](https://filament-34a8cf01.mintlify.site/5.x/forms/checkbox-list.md).

## Introduction

The checkbox list component allows you to select multiple values from a list of predefined options:

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\CheckboxList;

CheckboxList::make('technologies')
    ->options([
        'tailwind' => 'Tailwind CSS',
        'alpine' => 'Alpine.js',
        'laravel' => 'Laravel',
        'livewire' => 'Laravel Livewire',
    ])
```

<details>
  <summary />

  [Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/forms/overview.md#field-utility-injection)
</details>

Loading preview

![Checkbox list](https://filament-34a8cf01.mintlify.site/docs/images/4.x/light/forms/fields/checkbox-list/simple.jpg)

These options are returned in JSON format. If you're saving them using Eloquent, you should be sure to add an `array` [cast](https://laravel.com/docs/eloquent-mutators#array-and-json-casting) to the model property:

```php theme={"theme":"gruvbox-dark-hard"}
use Illuminate\Database\Eloquent\Model;

class App extends Model
{
    /**
     * @return array<string, string>
     */
    protected function casts(): array
    {
        return [
            'technologies' => 'array',
        ];
    }

    // ...
}
```

## Setting option descriptions

You can optionally provide descriptions to each option using the `descriptions()` method. This method accepts an array of plain text strings, or instances of `Illuminate\Support\HtmlString` or `Illuminate\Contracts\Support\Htmlable`. This allows you to render HTML, or even markdown, in the descriptions:

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\CheckboxList;
use Illuminate\Support\HtmlString;

CheckboxList::make('technologies')
    ->options([
        'tailwind' => 'Tailwind CSS',
        'alpine' => 'Alpine.js',
        'laravel' => 'Laravel',
        'livewire' => 'Laravel Livewire',
    ])
    ->descriptions([
        'tailwind' => 'A utility-first CSS framework for rapidly building modern websites without ever leaving your HTML.',
        'alpine' => new HtmlString('A rugged, minimal tool for composing behavior <strong>directly in your markup</strong>.'),
        'laravel' => str('A **web application** framework with expressive, elegant syntax.')->inlineMarkdown()->toHtmlString(),
        'livewire' => 'A full-stack framework for Laravel building dynamic interfaces simple, without leaving the comfort of Laravel.',
    ])
```

<details>
  <summary />

  [Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/forms/overview.md#field-utility-injection)
</details>

Loading preview

![Checkbox list with option descriptions](https://filament-34a8cf01.mintlify.site/docs/images/4.x/light/forms/fields/checkbox-list/option-descriptions.jpg)

> [!NOTE]
>
> Be sure to use the same `key` in the descriptions array as the `key` in the option array so the right description matches the right option.

## Splitting options into columns

You may split options into columns by using the `columns()` method:

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\CheckboxList;

CheckboxList::make('technologies')
    ->options([
        // ...
    ])
    ->columns(2)
```

<details>
  <summary />

  [Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/forms/overview.md#field-utility-injection)
</details>

Loading preview

![Checkbox list with 2 columns](https://filament-34a8cf01.mintlify.site/docs/images/4.x/light/forms/fields/checkbox-list/columns.jpg)

This method accepts the same options as the `columns()` method of the [grid](https://filament-34a8cf01.mintlify.site/4.x/schemas/layouts.md#grid-system). This allows you to responsively customize the number of columns at various breakpoints.

### Setting the grid direction

By default, when you arrange checkboxes into columns, they will be listed in order vertically. If you'd like to list them horizontally, you may use the `gridDirection(GridDirection::Row)` method:

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\CheckboxList;
use Filament\Support\Enums\GridDirection;

CheckboxList::make('technologies')
    ->options([
        // ...
    ])
    ->columns(2)
    ->gridDirection(GridDirection::Row)
```

<details>
  <summary />

  [Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/forms/overview.md#field-utility-injection)
</details>

Loading preview

![Checkbox list with 2 rows](https://filament-34a8cf01.mintlify.site/docs/images/4.x/light/forms/fields/checkbox-list/rows.jpg)

## Searching options

You may enable a search input to allow easier access to many options, using the `searchable()` method:

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\CheckboxList;

CheckboxList::make('technologies')
    ->options([
        // ...
    ])
    ->searchable()
```

Loading preview

![Searchable checkbox list](https://filament-34a8cf01.mintlify.site/docs/images/4.x/light/forms/fields/checkbox-list/searchable.jpg)

Optionally, you may pass a boolean value to control if the options should be searchable or not:

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\CheckboxList;

CheckboxList::make('technologies')
    ->options([
        // ...
    ])
    ->searchable(FeatureFlag::active())
```

<details>
  <summary />

  [Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/forms/overview.md#field-utility-injection)
</details>

## Bulk toggling checkboxes

You may allow users to toggle all checkboxes at once using the `bulkToggleable()` method:

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\CheckboxList;

CheckboxList::make('technologies')
    ->options([
        // ...
    ])
    ->bulkToggleable()
```

Loading preview

![Bulk toggleable checkbox list](https://filament-34a8cf01.mintlify.site/docs/images/4.x/light/forms/fields/checkbox-list/bulk-toggleable.jpg)

Optionally, you may pass a boolean value to control if the checkboxes should be bulk toggleable or not:

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\CheckboxList;

CheckboxList::make('technologies')
    ->options([
        // ...
    ])
    ->bulkToggleable(FeatureFlag::active())
```

<details>
  <summary />

  [Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/forms/overview.md#field-utility-injection)
</details>

## Disabling specific options

You can disable specific options using the `disableOptionWhen()` method. It accepts a closure, in which you can check if the option with a specific `$value` should be disabled:

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\CheckboxList;

CheckboxList::make('technologies')
    ->options([
        'tailwind' => 'Tailwind CSS',
        'alpine' => 'Alpine.js',
        'laravel' => 'Laravel',
        'livewire' => 'Laravel Livewire',
    ])
    ->disableOptionWhen(fn (string $value): bool => $value === 'livewire')
```

Loading preview

![Checkbox list with disabled option](https://filament-34a8cf01.mintlify.site/docs/images/4.x/light/forms/fields/checkbox-list/disabled-options.jpg)

<details>
  <summary />

  [Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/forms/overview.md#field-utility-injection)
</details>

If you want to retrieve the options that have not been disabled, e.g. for validation purposes, you can do so using `getEnabledOptions()`:

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\CheckboxList;

CheckboxList::make('technologies')
    ->options([
        'tailwind' => 'Tailwind CSS',
        'alpine' => 'Alpine.js',
        'laravel' => 'Laravel',
        'livewire' => 'Laravel Livewire',
        'heroicons' => 'SVG icons',
    ])
    ->disableOptionWhen(fn (string $value): bool => $value === 'heroicons')
    ->in(fn (CheckboxList $component): array => array_keys($component->getEnabledOptions()))
```

For more information about the `in()` function, please see the [Validation documentation](https://filament-34a8cf01.mintlify.site/4.x/forms/validation.md#in).

## Allowing HTML in the option labels

By default, Filament will escape any HTML in the option labels. If you'd like to allow HTML, you can use the `allowHtml()` method:

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\CheckboxList;

CheckboxList::make('technology')
    ->options([
        'tailwind' => '<span class="text-blue-500">Tailwind</span>',
        'alpine' => '<span class="text-green-500">Alpine</span>',
        'laravel' => '<span class="text-red-500">Laravel</span>',
        'livewire' => '<span class="text-pink-500">Livewire</span>',
    ])
    ->searchable()
    ->allowHtml()
```

Loading preview

![Checkbox list with HTML labels](https://filament-34a8cf01.mintlify.site/docs/images/4.x/light/forms/fields/checkbox-list/html-labels.jpg)

> [!CAUTION]
>
> Be aware that you will need to ensure that the HTML is safe to render, otherwise your application will be vulnerable to XSS attacks.

Optionally, you may pass a boolean value to control if the options should allow HTML or not:

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\CheckboxList;

CheckboxList::make('technology')
    ->options([
        'tailwind' => '<span class="text-blue-500">Tailwind</span>',
        'alpine' => '<span class="text-green-500">Alpine</span>',
        'laravel' => '<span class="text-red-500">Laravel</span>',
        'livewire' => '<span class="text-pink-500">Livewire</span>',
    ])
    ->searchable()
    ->allowHtml(FeatureFlag::active())
```

<details>
  <summary />

  [Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/forms/overview.md#field-utility-injection)
</details>

## Integrating with an Eloquent relationship

> If you're building a form inside your Livewire component, make sure you have set up the [form's model](https://filament-34a8cf01.mintlify.site/4.x/components/form.md#setting-a-form-model). Otherwise, Filament doesn't know which model to use to retrieve the relationship from.

You may employ the `relationship()` method of the `CheckboxList` to point to a `BelongsToMany` relationship. Filament will load the options from the relationship, and save them back to the relationship's pivot table when the form is submitted. The `titleAttribute` is the name of a column that will be used to generate a label for each option:

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\CheckboxList;

CheckboxList::make('technologies')
    ->relationship(titleAttribute: 'name')
```

> [!WARNING]
>
> When using `disabled()` with `relationship()`, ensure that `disabled()` is called before `relationship()`. This ensures that the `saved()` call from `disabled()` is not applied after the `relationship()` configuration:
>
> ```php theme={"theme":"gruvbox-dark-hard"}
> use Filament\Forms\Components\CheckboxList;
>
> CheckboxList::make('technologies')
>     ->disabled()
>     ->relationship(titleAttribute: 'name')
> ```

### Customizing the relationship query

You may customize the database query that retrieves options using the `modifyOptionsQueryUsing` parameter of the `relationship()` method:

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\CheckboxList;
use Illuminate\Database\Eloquent\Builder;

CheckboxList::make('technologies')
    ->relationship(
        titleAttribute: 'name',
        modifyQueryUsing: fn (Builder $query) => $query->withTrashed(),
    )
```

<details>
  <summary />

  [Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/forms/overview.md#field-utility-injection)
</details>

### Customizing the relationship option labels

If you'd like to customize the label of each option, maybe to be more descriptive, or to concatenate a first and last name, you could use a virtual column in your database migration:

```php theme={"theme":"gruvbox-dark-hard"}
$table->string('full_name')->virtualAs('concat(first_name, \' \', last_name)');
```

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\CheckboxList;

CheckboxList::make('authors')
    ->relationship(titleAttribute: 'full_name')
```

Alternatively, you can use the `getOptionLabelFromRecordUsing()` method to transform an option's Eloquent model into a label:

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\CheckboxList;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;

CheckboxList::make('authors')
    ->relationship(
        modifyQueryUsing: fn (Builder $query) => $query->orderBy('first_name')->orderBy('last_name'),
    )
    ->getOptionLabelFromRecordUsing(fn (Model $record) => "{$record->first_name} {$record->last_name}")
```

<details>
  <summary />

  [Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/forms/overview.md#field-utility-injection)
</details>

### Customizing the relationship option descriptions

If you'd like to customize the description of each option, you can use the `getOptionDescriptionFromRecordUsing()` method to transform an option's Eloquent model into a description:

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\CheckboxList;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;

CheckboxList::make('authors')
    ->relationship(
        modifyQueryUsing: fn (Builder $query) => $query->orderBy('first_name')->orderBy('last_name'),
    )
    ->getOptionDescriptionFromRecordUsing(fn (Model $record) => $record->notes)
```

<details>
  <summary />

  [Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/forms/overview.md#field-utility-injection)
</details>

### Saving pivot data to the relationship

If your pivot table has additional columns, you can use the `pivotData()` method to specify the data that should be saved in them:

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\CheckboxList;

CheckboxList::make('primaryTechnologies')
    ->relationship(name: 'technologies', titleAttribute: 'name')
    ->pivotData([
        'is_primary' => true,
    ])
```

<details>
  <summary />

  [Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/forms/overview.md#field-utility-injection)
</details>

## Setting a custom no search results message

When you're using a searchable checkbox list, you may want to display a custom message when no search results are found. You can do this using the `noSearchResultsMessage()` method:

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\CheckboxList;

CheckboxList::make('technologies')
    ->options([
        // ...
    ])
    ->searchable()
    ->noSearchResultsMessage('No technologies found.')
```

<details>
  <summary />

  [Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/forms/overview.md#field-utility-injection)
</details>

## Setting a custom search prompt

When you're using a searchable checkbox list, you may want to tweak the search input's placeholder when the user has not yet entered a search term. You can do this using the `searchPrompt()` method:

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\CheckboxList;

CheckboxList::make('technologies')
    ->options([
        // ...
    ])
    ->searchable()
    ->searchPrompt('Search for a technology')
```

<details>
  <summary />

  [Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/forms/overview.md#field-utility-injection)
</details>

## Tweaking the search debounce

By default, Filament will wait 1000 milliseconds (1 second) before searching for options when the user types in a searchable checkbox list. It will also wait 1000 milliseconds between searches if the user is continuously typing into the search input. You can change this using the `searchDebounce()` method:

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\CheckboxList;

CheckboxList::make('technologies')
    ->options([
        // ...
    ])
    ->searchable()
    ->searchDebounce(500)
```

<details>
  <summary />

  [Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/forms/overview.md#field-utility-injection)
</details>

## Customizing the checkbox list action objects

This field uses action objects for easy customization of buttons within it. You can customize these buttons by passing a function to an action registration method. The function has access to the `$action` object, which you can use to [customize it](https://filament-34a8cf01.mintlify.site/4.x/actions/overview.md). The following methods are available to customize the actions:

* `selectAllAction()`
* `deselectAllAction()`

Here is an example of how you might customize an action:

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Actions\Action;
use Filament\Forms\Components\CheckboxList;

CheckboxList::make('technologies')
    ->options([
        // ...
    ])
    ->selectAllAction(
        fn (Action $action) => $action->label('Select all technologies'),
    )
```

<details>
  <summary />

  [Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/forms/overview.md#field-utility-injection)
</details>

[Edit this page on GitHub](https://github.com/filamentphp/filament/edit/4.x/packages/forms/docs/06-checkbox-list.md)

## Sponsored by

[Your logo here](https://github.com/sponsors/danharrin)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.