Saltar al contenido principal

Checkbox list

Introducción​

El componente de lista de checkboxes te permite seleccionar múltiples valores de una lista de opciones predefinidas:

use Filament\Forms\Components\CheckboxList;

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

Además de permitir un array estático, el método options() también acepta una función para calcularlo dinámicamente. Puedes inyectar varias utilidades en la función como parámetros.

Estas opciones se devuelven en formato JSON. Si las estás guardando usando Eloquent, debes asegurarte de agregar un array cast a la propiedad del modelo:

use Illuminate\Database\Eloquent\Model;

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

    // ...
}

Establecer descripciones de opciones​

Opcionalmente puedes proporcionar descripciones para cada opción usando el método descriptions(). Este método acepta un array de strings de texto plano, o instancias de Illuminate\Support\HtmlString o Illuminate\Contracts\Support\Htmlable. Esto te permite renderizar HTML, o incluso markdown, en las descripciones:

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.',
    ])
Inyección de utilidades

Además de permitir un array estático, el método descriptions() también acepta una función para calcularlo dinámicamente. Puedes inyectar varias utilidades en la función como parámetros.

info

Asegúrate de usar la misma key en el array de descripciones que la key en el array de opciones para que la descripción correcta coincida con la opción correcta.

Dividir opciones en columnas​

Puedes dividir opciones en columnas usando el método columns():

use Filament\Forms\Components\CheckboxList;

CheckboxList::make('technologies')
    ->options([
        // ...
    ])
    ->columns(2)
Inyección de utilidades

Además de permitir un valor estático, el método columns() también acepta una función para calcularlo dinámicamente. Puedes inyectar varias utilidades en la función como parámetros.

Este método acepta las mismas opciones que el método columns() del grid. Esto te permite personalizar de forma responsiva el número de columnas en varios breakpoints.

Establecer la dirección del grid​

Por defecto, cuando organizas checkboxes en columnas, se listarán en orden vertical. Si prefieres listarlos horizontalmente, puedes usar el método gridDirection(GridDirection::Row):

use Filament\Forms\Components\CheckboxList;
use Filament\Support\Enums\GridDirection;

CheckboxList::make('technologies')
    ->options([
        // ...
    ])
    ->columns(2)
    ->gridDirection(GridDirection::Row)
Inyección de utilidades

Además de permitir un valor estático, el método gridDirection() también acepta una función para calcularlo dinámicamente. Puedes inyectar varias utilidades en la función como parámetros.

Buscar opciones​

Puedes habilitar un campo de búsqueda para permitir un acceso más fácil a muchas opciones, usando el método searchable():

use Filament\Forms\Components\CheckboxList;

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

Opcionalmente, puedes pasar un valor booleano para controlar si las opciones deben ser buscables o no:

use Filament\Forms\Components\CheckboxList;

CheckboxList::make('technologies')
    ->options([
        // ...
    ])
    ->searchable(FeatureFlag::active())
Inyección de utilidades

Además de permitir un valor estático, el método searchable() también acepta una función para calcularlo dinámicamente. Puedes inyectar varias utilidades en la función como parámetros.

Alternar checkboxes en bloque​

Puedes permitir que los usuarios alternen todos los checkboxes a la vez usando el método bulkToggleable():

use Filament\Forms\Components\CheckboxList;

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

Opcionalmente, puedes pasar un valor booleano para controlar si los checkboxes deben poder alternarse en bloque o no:

use Filament\Forms\Components\CheckboxList;

CheckboxList::make('technologies')
    ->options([
        // ...
    ])
    ->bulkToggleable(FeatureFlag::active())
Inyección de utilidades

Además de permitir un valor estático, el método bulkToggleable() también acepta una función para calcularlo dinámicamente. Puedes inyectar varias utilidades en la función como parámetros.

Deshabilitar opciones específicas​

Puedes deshabilitar opciones específicas usando el método disableOptionWhen(). Acepta un closure, en el cual puedes comprobar si la opción con un $value específico debe estar deshabilitada:

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')
Inyección de utilidades

Puedes inyectar varias utilidades en la función como parámetros.

Parámetros adicionales disponibles:
  • Valor de opción (mixed $value) - El valor de la opción a deshabilitar.
  • Etiqueta de opción (string | Illuminate\Contracts\Support\Htmlable $label) - La etiqueta de la opción a deshabilitar.

Si quieres recuperar las opciones que no han sido deshabilitadas, por ejemplo con fines de validación, puedes hacerlo usando getEnabledOptions():

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()))

Para más información sobre la función in(), consulta la documentación de Validación.

Permitir HTML en las etiquetas de las opciones​

Por defecto, Filament escapará cualquier HTML en las etiquetas de las opciones. Si quieres permitir HTML, puedes usar el método allowHtml():

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()
peligro

Ten en cuenta que deberás asegurarte de que el HTML sea seguro para renderizar, de lo contrario tu aplicación será vulnerable a ataques XSS.

Opcionalmente, puedes pasar un valor booleano para controlar si las opciones deben permitir HTML o no:

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())
Inyección de utilidades

Además de permitir un valor estático, el método allowHtml() también acepta una función para calcularlo dinámicamente. Puedes inyectar varias utilidades en la función como parámetros.

Integración con una relación Eloquent​

Si estás construyendo un formulario dentro de tu componente Livewire, asegúrate de haber configurado el modelo del formulario. De lo contrario, Filament no sabrá qué modelo usar para recuperar la relación.

Puedes usar el método relationship() de CheckboxList para apuntar a una relación BelongsToMany. Filament cargará las opciones desde la relación, y las guardará de vuelta en la tabla pivot cuando se envíe el formulario. El titleAttribute es el nombre de una columna que se usará para generar una etiqueta para cada opción:

use Filament\Forms\Components\CheckboxList;

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

Al usar disabled() con relationship(), asegúrate de que disabled() se llame antes de relationship(). Esto asegura que la llamada a dehydrated() desde dentro de relationship() no sea sobrescrita por la llamada desde disabled():

use Filament\Forms\Components\CheckboxList;

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

Personalizar la consulta de la relación​

Puedes personalizar la consulta de base de datos que recupera opciones usando el parámetro modifyOptionsQueryUsing del método relationship():

use Filament\Forms\Components\CheckboxList;
use Illuminate\Database\Eloquent\Builder;

CheckboxList::make('technologies')
    ->relationship(
        titleAttribute: 'name',
        modifyQueryUsing: fn (Builder $query) => $query->withTrashed(),
    )
Inyección de utilidades

El argumento modifyQueryUsing puede inyectar varias utilidades en la función como parámetros.

Parámetros adicionales disponibles:
  • Query (Illuminate\Database\Eloquent\Builder $query) - El query builder de Eloquent a modificar.

Personalizar las etiquetas de opciones de la relación​

Si quieres personalizar la etiqueta de cada opción, tal vez para ser más descriptivo, o para concatenar nombre y apellido, podrías usar una columna virtual en tu migración de base de datos:

$table->string('full_name')->virtualAs('concat(first_name, \' \' , last_name)');
use Filament\Forms\Components\CheckboxList;

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

Alternativamente, puedes usar el método getOptionLabelFromRecordUsing() para transformar el modelo Eloquent de una opción en una etiqueta:

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}")
Inyección de utilidades

El método getOptionLabelFromRecordUsing() puede inyectar varias utilidades en la función como parámetros.

Parámetros adicionales disponibles:
  • Registro Eloquent (Illuminate\Database\Eloquent\Model $record) - El registro Eloquent para obtener la etiqueta de la opción.

Guardar datos pivot en la relación​

Si tu tabla pivot tiene columnas adicionales, puedes usar el método pivotData() para especificar los datos que deben guardarse en ellas:

use Filament\Forms\Components\CheckboxList;

CheckboxList::make('primaryTechnologies')
    ->relationship(name: 'technologies', titleAttribute: 'name')
    ->pivotData([
        'is_primary' => true,
    ])
Inyección de utilidades

Además de permitir un valor estático, el método pivotData() también acepta una función para calcularlo dinámicamente. Puedes inyectar varias utilidades en la función como parámetros.

Establecer un mensaje personalizado cuando no hay resultados de búsqueda​

Cuando usas una lista de checkboxes buscable, puede que quieras mostrar un mensaje personalizado cuando no se encuentren resultados de búsqueda. Puedes hacerlo usando el método noSearchResultsMessage():

use Filament\Forms\Components\CheckboxList;

CheckboxList::make('technologies')
    ->options([
        // ...
    ])
    ->searchable()
    ->noSearchResultsMessage('No technologies found.')
Inyección de utilidades

Además de permitir un valor estático, el método noSearchResultsMessage() también acepta una función para calcularlo dinámicamente. Puedes inyectar varias utilidades en la función como parámetros.

Establecer un prompt de búsqueda personalizado​

Cuando usas una lista de checkboxes buscable, puedes ajustar el placeholder del campo de búsqueda cuando el usuario aún no ha introducido un término. Puedes hacerlo usando el método searchPrompt():

use Filament\Forms\Components\CheckboxList;

CheckboxList::make('technologies')
    ->options([
        // ...
    ])
    ->searchable()
    ->searchPrompt('Search for a technology')
Inyección de utilidades

Además de permitir un valor estático, el método searchPrompt() también acepta una función para calcularlo dinámicamente. Puedes inyectar varias utilidades en la función como parámetros.

Ajustar el debounce de búsqueda​

Por defecto, Filament esperará 1000 milisegundos (1 segundo) antes de buscar opciones cuando el usuario escribe en una lista de checkboxes buscable. También esperará 1000 milisegundos entre búsquedas si el usuario está escribiendo continuamente en el campo de búsqueda. Puedes cambiar esto usando el método searchDebounce():

use Filament\Forms\Components\CheckboxList;

CheckboxList::make('technologies')
    ->options([
        // ...
    ])
    ->searchable()
    ->searchDebounce(500)
Inyección de utilidades

Además de permitir un valor estático, el método searchDebounce() también acepta una función para calcularlo dinámicamente. Puedes inyectar varias utilidades en la función como parámetros.

Personalizar los objetos de acción de la lista de checkboxes​

Este campo usa objetos de acción para una fácil personalización de los botones dentro de él. Puedes personalizar estos botones pasando una función a un método de registro de acciones. La función tiene acceso al objeto $action, que puedes usar para personalizarlo. Los siguientes métodos están disponibles para personalizar las acciones:

  • selectAllAction()
  • deselectAllAction()

Aquí hay un ejemplo de cómo podrías personalizar una acción:

use Filament\Actions\Action;
use Filament\Forms\Components\CheckboxList;

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

Los métodos de registro de acciones pueden inyectar varias utilidades en la función como parámetros.

Parámetros adicionales disponibles:
  • Action (Filament\Actions\Action $action) - El objeto action a personalizar.