Select

#简介

Select 组件允许你从一个预定义选项列表中选择一个或多个值：

use Filament\Forms\Components\Select;

Select::make('status')
    ->options([
        'draft' => 'Draft',
        'reviewing' => 'Reviewing',
        'published' => 'Published',
    ])

#启用 JavaScript 版 Select

默认情况下，Filament 使用原生 HTML5 的 Select。通过 native(false) 方法，你可以启用更多自定义的 JavaScript 版 Select：

use Filament\Forms\Components\Select;

Select::make('status')
    ->options([
        'draft' => 'Draft',
        'reviewing' => 'Reviewing',
        'published' => 'Published',
    ])
    ->native(false)

#搜索选项

使用 searchable()，你可以启用搜索输入框，以允许用户更容易访问多选项：

use Filament\Forms\Components\Select;

Select::make('author_id')
    ->label('Author')
    ->options(User::query()->pluck('name', 'id'))
    ->searchable()

此外，你也可以传入一个布尔值以控制其是否是可搜索的：

use Filament\Forms\Components\Select;

Select::make('author_id')
    ->label('Author')
    ->options(User::query()->pluck('name', 'id'))
    ->searchable(FeatureFlag::active())

#返回自定义搜索结果

如果你有大量的选项，且希望基于数据搜索或者其他外部数据源填充这些选项，你可以使用 getSearchResultsUsing() 和 getOptionLabelUsing()，而不是 options()。

getSearchResultsUsing() 方法接受一个回调函数，该回调以 $key => $value 格式返回搜索结果。当前用户的搜索结果可以通过 $search 获得，你应该使用它来过滤结果。

getOptionLabelUsing() 方法接受一个回调函数，该回调将选中的选项的 $value 值转换成标签。这用于用户还未进行搜索时的表单首次加载，该标签用于显示当前选则的选项还不可用。

如果你想提供自定义搜索结果，则必须在 Select 上同时使用 getSearchResultsUsing() 和 getOptionLabelUsing()：

use Filament\Forms\Components\Select;

Select::make('author_id')
    ->searchable()
    ->getSearchResultsUsing(fn (string $search): array => User::query()
        ->where('name', 'like', "%{$search}%")
        ->limit(50)
        ->pluck('name', 'id')
        ->all())
    ->getOptionLabelUsing(fn ($value): ?string => User::find($value)?->name),

#设置自定义加载消息

当用户使用可搜索 Select 或多选时，你可能希望在选项加载时显示自定义消息，你可以使用 loadingMessage() 来实现：

use Filament\Forms\Components\Select;

Select::make('author_id')
    ->relationship(name: 'author', titleAttribute: 'name')
    ->searchable()
    ->loadingMessage('Loading authors...')

#设置无搜索结果的消息

当用户使用可搜索 Select 或多选时，你可能希望在未找到搜索结果时显示自定义消息，你可以使用 noSearchResultsMessage() 方法来实现：

use Filament\Forms\Components\Select;

Select::make('author_id')
    ->relationship(name: 'author', titleAttribute: 'name')
    ->searchable()
    ->noSearchResultsMessage('No authors found.')

#设置自定义搜索提示

When you’re using a searchable select or multi-select, you may want to display a custom message when the user has not yet entered a search term. You can do this using the searchPrompt() method:

use Filament\Forms\Components\Select;

Select::make('author_id')
    ->relationship(name: 'author', titleAttribute: 'name')
    ->searchable(['name', 'email'])
    ->searchPrompt('Search authors by their name or email address')

#设置自定义搜索消息

When you’re using a searchable select or multi-select, you may want to display a custom message while the search results are being loaded. You can do this using the searchingMessage() method:

use Filament\Forms\Components\Select;

Select::make('author_id')
    ->relationship(name: 'author', titleAttribute: 'name')
    ->searchable()
    ->searchingMessage('Searching authors...')

#调整搜索抖动

By default, Filament will wait 1000 milliseconds (1 second) before searching for options when the user types in a searchable select or multi-select. 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:

use Filament\Forms\Components\Select;

Select::make('author_id')
    ->relationship(name: 'author', titleAttribute: 'name')
    ->searchable()
    ->searchDebounce(500)

Ensure that you are not lowering the debounce too much, as this may cause the select to become slow and unresponsive due to a high number of network requests to retrieve options from server.

#多选

Select 组件上的 multiple() 方法允许你从选项列表中选择多个值：

use Filament\Forms\Components\Select;

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

此外，你也可以传入布尔值以控制该字段是否可多选：

use Filament\Forms\Components\Select;

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

这些选项以 JSON 格式返回。如果你在 Eloquent 中保存，请确保添加 array cast 转换 到模型属性上：

use Illuminate\Database\Eloquent\Model;

class App extends Model
{
    protected $casts = [
        'technologies' => 'array',
    ];

    // ...
}

如果你返回自定义搜索结果，你应该定义 getOptionLabelsUsing() 而非 getOptionLabelUsing()。$values 将传入到回调中，而非 $value，你应该返回$key => $value 标签数组以及他们对应的值：

Select::make('technologies')
    ->multiple()
    ->searchable()
    ->getSearchResultsUsing(fn (string $search): array => Technology::query()
        ->where('name', 'like', "%{$search}%")
        ->limit(50)
        ->pluck('name', 'id')
        ->all())
    ->getOptionLabelsUsing(fn (array $values): array => Technology::query()
        ->whereIn('id', $values)
        ->pluck('name', 'id')
        ->all()),

#选项分组

你可以将选项分组到一个标签之下，以便更好地组织这些选项。为此，你可以传递分组数组到 options() 方法或者其他你传递选项数组的方法。数组的键用作分组的标签，而其值未该分组下的选项数组：

use Filament\Forms\Components\Select;

Select::make('status')
    ->searchable()
    ->options([
        'In Process' => [
            'draft' => 'Draft',
            'reviewing' => 'Reviewing',
        ],
        'Reviewed' => [
            'published' => 'Published',
            'rejected' => 'Rejected',
        ],
    ])

#整合 Eloquent 关联

你可以使用 Select() 的 relationship() 方法去配置 BelongsTo 关联，使之自动检索选项。titleAttribute 是用以生成每个选项标签的字段名：

use Filament\Forms\Components\Select;

Select::make('author_id')
    ->relationship(name: 'author', titleAttribute: 'name')

The multiple() method may be used in combination with relationship() to use 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. If a name is not provided, Filament will use the field name as the relationship name:

use Filament\Forms\Components\Select;

Select::make('technologies')
    ->multiple()
    ->relationship(titleAttribute: 'name')

use Filament\Forms\Components\Select;

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

#Searching relationship options across multiple columns

By default, if the select is also searchable, Filament will return search results for the relationship based on the title column of the relationship. If you’d like to search across multiple columns, you can pass an array of columns to the searchable() method:

use Filament\Forms\Components\Select;

Select::make('author_id')
    ->relationship(name: 'author', titleAttribute: 'name')
    ->searchable(['name', 'email'])

#Preloading relationship options

If you’d like to populate the searchable options from the database when the page is loaded, instead of when the user searches, you can use the preload() method:

use Filament\Forms\Components\Select;

Select::make('author_id')
    ->relationship(name: 'author', titleAttribute: 'name')
    ->searchable()
    ->preload()

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

use Filament\Forms\Components\Select;

Select::make('author_id')
    ->relationship(name: 'author', titleAttribute: 'name')
    ->searchable()
    ->preload(FeatureFlag::active())

#Excluding the current record

When working with recursive relationships, you will likely want to remove the current record from the set of results.

This can be easily be done using the ignoreRecord argument:

use Filament\Forms\Components\Select;

Select::make('parent_id')
    ->relationship(name: 'parent', titleAttribute: 'name', ignoreRecord: true)

#Customizing the relationship query

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

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

Select::make('author_id')
    ->relationship(
        name: 'author',
        titleAttribute: 'name',
        modifyQueryUsing: fn (Builder $query) => $query->withTrashed(),
    )

#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:

$table->string('full_name')->virtualAs('concat(first_name, \' \', last_name)');

use Filament\Forms\Components\Select;

Select::make('author_id')
    ->relationship(name: 'author', titleAttribute: 'full_name')

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

use Filament\Forms\Components\Select;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;

Select::make('author_id')
    ->relationship(
        name: 'author',
        modifyQueryUsing: fn (Builder $query) => $query->orderBy('first_name')->orderBy('last_name'),
    )
    ->getOptionLabelFromRecordUsing(fn (Model $record) => "{$record->first_name} {$record->last_name}")
    ->searchable(['first_name', 'last_name'])

#Saving pivot data to the relationship

If you’re using a multiple() relationship and your pivot table has additional columns, you can use the pivotData() method to specify the data that should be saved in them:

use Filament\Forms\Components\Select;

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

#Creating a new option in a modal

You may define a custom form that can be used to create a new record and attach it to the BelongsTo relationship:

use Filament\Forms\Components\Select;

Select::make('author_id')
    ->relationship(name: 'author', titleAttribute: 'name')
    ->createOptionForm([
        Forms\Components\TextInput::make('name')
            ->required(),
        Forms\Components\TextInput::make('email')
            ->required()
            ->email(),
    ]),

The form opens in a modal, where the user can fill it with data. Upon form submission, the new record is selected by the field.

#Customizing new option creation

You can customize the creation process of the new option defined in the form using the createOptionUsing() method, which should return the primary key of the newly created record:

use Filament\Forms\Components\Select;

Select::make('author_id')
    ->relationship(name: 'author', titleAttribute: 'name')
    ->createOptionForm([
       // ...
    ])
    ->createOptionUsing(function (array $data): int {
        return auth()->user()->team->members()->create($data)->getKey();
    }),

#Editing the selected option in a modal

You may define a custom form that can be used to edit the selected record and save it back to the BelongsTo relationship:

use Filament\Forms\Components\Select;

Select::make('author_id')
    ->relationship(name: 'author', titleAttribute: 'name')
    ->editOptionForm([
        Forms\Components\TextInput::make('name')
            ->required(),
        Forms\Components\TextInput::make('email')
            ->required()
            ->email(),
    ]),

The form opens in a modal, where the user can fill it with data. Upon form submission, the data from the form is saved back to the record.

#Customizing option updates

You can customize the update process of the selected option defined in the form using the updateOptionUsing() method. The current Eloquent record being edited can be retrieved using the getRecord() method on the schema:

use Filament\Forms\Components\Select;
use Filament\Schemas\Schema;

Select::make('author_id')
    ->relationship(name: 'author', titleAttribute: 'name')
    ->editOptionForm([
       // ...
    ])
    ->updateOptionUsing(function (array $data, Schema $schema) {
        $schema->getRecord()?->update($data);
    }),

#Handling MorphTo relationships

MorphTo relationships are special, since they give the user the ability to select records from a range of different models. Because of this, we have a dedicated MorphToSelect component which is not actually a select field, rather 2 select fields inside a fieldset. The first select field allows you to select the type, and the second allows you to select the record of that type.

To use the MorphToSelect, you must pass types() into the component, which tell it how to render options for different types:

use Filament\Forms\Components\MorphToSelect;

MorphToSelect::make('commentable')
    ->types([
        MorphToSelect\Type::make(Product::class)
            ->titleAttribute('name'),
        MorphToSelect\Type::make(Post::class)
            ->titleAttribute('title'),
    ])

#Customizing the option labels for each morphed type

The titleAttribute() is used to extract the titles out of each product or post. If you’d like to customize the label of each option, you can use the getOptionLabelFromRecordUsing() method to transform the Eloquent model into a label:

use Filament\Forms\Components\MorphToSelect;

MorphToSelect::make('commentable')
    ->types([
        MorphToSelect\Type::make(Product::class)
            ->getOptionLabelFromRecordUsing(fn (Product $record): string => "{$record->name} - {$record->slug}"),
        MorphToSelect\Type::make(Post::class)
            ->titleAttribute('title'),
    ])

#Customizing the relationship query for each morphed type

You may customize the database query that retrieves options using the modifyOptionsQueryUsing() method:

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

MorphToSelect::make('commentable')
    ->types([
        MorphToSelect\Type::make(Product::class)
            ->titleAttribute('name')
            ->modifyOptionsQueryUsing(fn (Builder $query) => $query->whereBelongsTo($this->team)),
        MorphToSelect\Type::make(Post::class)
            ->titleAttribute('title')
            ->modifyOptionsQueryUsing(fn (Builder $query) => $query->whereBelongsTo($this->team)),
    ])

#允许选项标签中使用 HTML

默认情况下，Filament 将转义选项标签中的 HTML。如果你希望允许使用 HTML，可以使用 allowHtml() 方法：

use Filament\Forms\Components\Select;

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

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

use Filament\Forms\Components\Select;

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

#Disable placeholder selection

You can prevent the placeholder (null option) from being selected using the selectablePlaceholder(false) method:

use Filament\Forms\Components\Select;

Select::make('status')
    ->options([
        'draft' => 'Draft',
        'reviewing' => 'Reviewing',
        'published' => 'Published',
    ])
    ->default('draft')
    ->selectablePlaceholder(false)

#禁用指定选项

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:

use Filament\Forms\Components\Select;

Select::make('status')
    ->options([
        'draft' => 'Draft',
        'reviewing' => 'Reviewing',
        'published' => 'Published',
    ])
    ->default('draft')
    ->disableOptionWhen(fn (string $value): bool => $value === 'published')

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

use Filament\Forms\Components\Select;

Select::make('status')
    ->options([
        'draft' => 'Draft',
        'reviewing' => 'Reviewing',
        'published' => 'Published',
    ])
    ->default('draft')
    ->disableOptionWhen(fn (string $value): bool => $value === 'published')
    ->in(fn (Select $component): array => array_keys($component->getEnabledOptions()))

For more information about the in() function, please see the Validation documentation.

#Adding affix text aside the field

You may place text before and after the input using the prefix() and suffix() methods:

use Filament\Forms\Components\Select;

Select::make('domain')
    ->prefix('https://')
    ->suffix('.com')

#使用图标作为前后缀

You may place an icon before and after the input using the prefixIcon() and suffixIcon() methods:

use Filament\Forms\Components\Select;
use Filament\Support\Icons\Heroicon;

Select::make('domain')
    ->suffixIcon(Heroicon::GlobeAlt)

#Setting the affix icon’s color

Affix icons are gray by default, but you may set a different color using the prefixIconColor() and suffixIconColor() methods:

use Filament\Forms\Components\Select;
use Filament\Support\Icons\Heroicon;

Select::make('domain')
    ->suffixIcon(Heroicon::CheckCircle)
    ->suffixIconColor('success')

#限制选项数量

You can limit the number of options that are displayed in a searchable select or multi-select using the optionsLimit() method. The default is 50:

use Filament\Forms\Components\Select;

Select::make('author_id')
    ->relationship(name: 'author', titleAttribute: 'name')
    ->searchable()
    ->optionsLimit(20)

Ensure that you are not raising the limit too high, as this may cause the select to become slow and unresponsive due to high in-browser memory usage.

#布尔值选项

If you want a simple boolean select, with “Yes” and “No” options, you can use the boolean() method:

use Filament\Forms\Components\Select;

Select::make('feedback')
    ->label('Like this post?')
    ->boolean()

To customize the “Yes” label, you can use the trueLabel argument on the boolean() method:

use Filament\Forms\Components\Select;

Select::make('feedback')
    ->label('Like this post?')
    ->boolean(trueLabel: 'Absolutely!')

To customize the “No” label, you can use the falseLabel argument on the boolean() method:

use Filament\Forms\Components\Select;

Select::make('feedback')
    ->label('Like this post?')
    ->boolean(falseLabel: 'Not at all!')

To customize the placeholder that shows when an option has not yet been selected, you can use the placeholder argument on the boolean() method:

use Filament\Forms\Components\Select;

Select::make('feedback')
    ->label('Like this post?')
    ->boolean(placeholder: 'Make your mind up...')

#Selecting options from a table in a modal

You can use the ModalTableSelect component to open a Filament table in a modal, allowing users to select records from it. This is useful when you have a relationship that has a lot of records, and you want users to be able to perform advanced filtering and searching through them.

To use the ModalTableSelect, you must have a table configuration class for the model. You can generate one of these classes using the make:filament-table command:

use Filament\Tables\Columns\TextColumn;
use Filament\Tables\Filters\SelectFilter;
use Filament\Tables\Table;

class CategoriesTable
{
    public static function configure(Table $table): Table
    {
        return $table
            ->columns([
                TextColumn::make('name')
                    ->searchable(),
                TextColumn::make('slug')
                    ->searchable(),
            ])
            ->filters([
                SelectFilter::make('parent')
                    ->relationship('parent', 'name')
                    ->searchable()
                    ->preload(),
            ]);
    }
}

The class must have a configure() method that accepts the Table object and returns it. The class name needs to be passed to the tableConfiguration() method of the ModalTableSelect component:

use Filament\Forms\Components\ModalTableSelect;

ModalTableSelect::make('category_id')
    ->relationship('category', 'name')
    ->tableConfiguration(CategoriesTable::class)

You can also use the multiple() method with a multiple relationship such as BelongsToMany:

use Filament\Forms\Components\ModalTableSelect;

ModalTableSelect::make('categories')
    ->relationship('categories', 'name')
    ->multiple()
    ->tableConfiguration(CategoriesTable::class)

You can customize the “Select” button and modal using the action object configuration methods. Passing a function to the selectAction() method allows you to modify the $action object, for example, to change the button label and the modal heading:

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

ModalTableSelect::make('category_id')
    ->relationship('category', 'name')
    ->tableConfiguration(CategoriesTable::class)
    ->selectAction(
        fn (Action $action) => $action
            ->label('Select a category')
            ->modalHeading('Search categories')
            ->modalSubmitActionLabel('Confirm selection'),
    )

The getOptionLabelFromRecordUsing() method can be used to customize the label of each selected option. This is useful if you want to display a more descriptive label or concatenate two columns together:

use Filament\Forms\Components\ModalTableSelect;

ModalTableSelect::make('category_id')
    ->relationship('category', 'name')
    ->tableConfiguration(CategoriesTable::class)
    ->getOptionLabelFromRecordUsing(fn (Category $record): string => "{$record->name} ({$record->slug})")

#Select validation

As well as all rules listed on the validation page, there are additional rules that are specific to selects.

#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:

use Filament\Forms\Components\Select;

Select::make('technologies')
    ->multiple()
    ->options([
        'tailwind' => 'Tailwind CSS',
        'alpine' => 'Alpine.js',
        'laravel' => 'Laravel',
        'livewire' => 'Laravel Livewire',
    ])
    ->minItems(1)
    ->maxItems(3)

#Customizing the select 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 or customize its modal. The following methods are available to customize the actions:

• createOptionAction()
• editOptionAction()
• manageOptionActions() (for customizing both the create and edit option actions at once)

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

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

Select::make('author_id')
    ->relationship(name: 'author', titleAttribute: 'name')
    ->createOptionAction(
        fn (Action $action) => $action->modalWidth('3xl'),
    )

Still need help? Join our Discord community or open a GitHub discussion