Download the PHP package dvarilek/filament-table-select without Composer

Filament Table Select

Installation

Overview

This package introduces a new Form component that acts as a replacement for the Select field by allowing users to select related records from a full-fledged Filament table through a relationship.

Naturally, using a table for selection provides much greater context and clarity, as users can interact with it like any other Filament table. The table can be fully customizable.

[!IMPORTANT]\ This package is only compatible with Filament v3.x. Starting with Filament v4.x, a new built-in component is available that offers a more polished and native implementation of similar functionality. See the ModalTableSelect documentation

Getting Started

Even though TableSelect doesn't extend the Select field directly, it borrows some functionality from it.

First, configure the relationship and title attribute using the relationship() method, which works the same way as in Filament's standard Select field. This method sets up a BelongsTo relationship to automatically retrieve options, where the titleAttribute specifies the column used to generate labels for each option.

Multi Selection

The multiple() method enables to use a belongsToMany() relationship, which allows to select and associate multiple records.

Selected Items Validation

You can validate the minimum and maximum number of items that you can select in a multi-select by setting the minItems() and maxItems() methods:

[!NOTE]\ If maxItems(1) is set to 1, radio-like selection gets enabled regardless of the relationship type.

Customizing Selected Options

Label Configuration

The TableSelect field enables for customization of selected options and their badges.

To customize the color of selected options, use the optionColor() method:

To customize the icon of selected options, use the optionIcon() method:

Even though both optionColor() and optionIcon() methods accept callbacks, they cannot work with the given record instance. This is done for performance reasons, so all selected options are not loaded into memory on each request.

To customize the colors of selected options while being able to access the Eloquent model instance, use the getOptionColorFromRecordUsing() method.

To customize the icons of selected options while being able to access the Eloquent model instance, use the getOptionIconFromRecordUsing() method.

To customize the labels of selected options while being able to access the Eloquent model instance, use the getOptionLabelFromRecordUsing() method.

Other Configuration Options

To customize the size of selected option badges, use the optionSize() method:

To customize the size of selected option badges, use the optionIconSize() method:

Selection Table

Selection Table Configuration

You can configure the Selection table by passing a closure into the selectionTable() method, this is where you can add columns, remove actions, modify the table's query etc.

Configuring the table is really important, especially defining the table columns. Without explicitly defining table columns, you would be presented with an empty table.

[!IMPORTANT]\ The context of this selectionTable callback is scoped to the Livewire component instance where it's evaluated. You cannot inject Filament utilities like Get $get or Set $set here. To use outside context within this closure, see here

To use an already defined table from a Filament Resource, use the tableLocation() method, this can be done together with selectionTable():

Working with arguments within Selection Table

To bring outside context into the selectionTable Closure, use the selectionTableArguments method.

Suppose we have a Project Resource and a project record that can be associated with multiple employees. This Project belongs to a specific Branch. Employees also belong to branches, so we want to limit the employee selection to only those in the same branch as the Project.

If you want to replace the Livewire component entirely, use the selectionTableLivewire method and provide a subclass of SelectionTable::class. This is useful if you rely on other external packages that require you to, for example, add traits to livewire components for functionality.

Selection Action

Selection Action Configuration

The selection action and its modal, where the table is contained, can be configured using the selectionAction() method:

Selection Action Position

By default, the selection action is displayed in the left bottom corner. To change its position, use the selectionActionAlignment() method:

Or provide an optional parameter directly in the selectionAction() method:

Opening Selection Modal On Click

If you with to hide this action and open the modal by clicking on the Field directly, use the triggerSelectionActionOnInputClick() method:

Or provide an optional parameter directly in the selectionAction() method:

[!NOTE]\ Having this feature enabled still requires the selection action itself to be visible, because it needs to get mounted.

Confirmation action

Selection Confirmation

By default, the component's state is automatically updated as records are selected. To require a confirmation of the selection, use the requiresSelectionConfirmation() method:

This prevents automatic state updates and adds a confirmation action to the modal. Only when this action is clicked will the form component's state get updated.

[!IMPORTANT]\ If you're concerned about performance, especially when updating the state would load a large number of models (e.g., when using one of the getOptionFromRecord methods), consider enabling this feature.

Closing After Selection

After confirmation, the modal closes by default. To keep it open, use the shouldCloseAfterSelection():

Or provide an optional parameter directly in the requiresSelectionConfirmation() method:

[!NOTE]\ Obviously, this only takes effect when selection confirmation is enabled.

Selection Action Position

By default, the confirmation action is positioned in the bottom left corner of the modal. To change its position use the confirmationActionPosition() method:

Or provide an optional parameter directly in the requiresSelectionConfirmation() method:

Creating New Records

Create Option Action

In a standard Select field, if users can’t find the record they need, they can create and associate a new one on using the createOptionAction(). - Official Filament Documentation

The TableSelect borrows this exact functionality and displays the create option action in the selection modal. To configure this action you can use the following methods:

[!IMPORTANT] When a new record is created, it's automatically selected in the table. If this newly created record exceeds the selection limit, the record naturally won't be selected. Obviously, in single-selection mode, the new record will replace the old one.

Create Option Action Position

By default, the create option action is positioned in the top right corner of the modal. To change its position use the createOptionActionPosition() method:

Advanced

To globally configure all TableSelect component instances, use the configureUsing() method in you application's Service Provider boot method:

Testing

Changelog

Please refer to Package Releases for more information about changes.

License

This package is under the MIT License. Please refer to License File for more information