Component

See below for an overview of all possible configuration options (in addition to the standard form component options, like label, helper text, hint, columns, etc.).

Selecting multiple records

You can allow selecting multiple records by using the ->multiple() method:

RecordFinder::make('product_ids')
    ->multiple()

Displaying selected records

By default, the Record Finder will allow you to display the selected records in a variety of ways. For each record we will determine a label based on the (ID of the) Eloquent model(s) that was selected. In most cases, you would need to provide an attribute name to ->recordLabelAttribute() to set the attribute that should be used as the label. For example:

RecordFinder::make('product_id')
    ->query(Product::query())
    // Provide an attribute available on the `Product` model that will be used as the label to identify a record:
    ->recordLabelAttribute('title'),

You can also provide a closure to manually construct a label for each record:

RecordFinder::make('product_id')
    ->query(Product::query())
    ->getRecordLabelFromRecordUsing(fn (Product $product) => "{$product->title} ({$product->sku})")
    // If you have a `->multiple()` Record Finder, then this closure will run individually for every selected record
    // that is visible in the list, meaning that you can always assume an individual Eloquent model to be injected...

If you do not provide a value or a closure to ->recordLabelAttribute() or ->getRecordLabelFromRecordUsing(), then the package will try to determine a label automatically based on the following fallback order:

1. Check if the Eloquent model implements the Filament\Support\Contracts\HasLabel contract. If so, use the getLabel() method.
2. Check if the Eloquent model implements the Filament\Models\Contracts\HasFilamentName contract. If so, use the getFilamentName() method.
3. Check if the Eloquent model has any of the following default attributes: title, name or full_name. If so, use these attributes (in the order given).
4. Finally, if none of the above provide a result, use the model key as fallback.

Displaying as a (bulleted) list

By default, the label for the selected records will display as pure text. If you have selected multiple records, then the labels for the records are joined together into a comma-separated list.

You can also choose to display the selected records as a list with line breaks:

RecordFinder::make('products')
    ->multiple()
    ->listWithLineBreaks()

This will display the selected records as an <ul> list with line breaks, but without bullets. If you want to display the items as a bulleted list, use the ->bulleted() method instead:

RecordFinder::make('products')
    ->multiple()
    ->bulleted()

This configuration method and the following ones work the same as Filament's TextEntry infolist component.

Limiting nr. of records in list

If you want to limit the number of records that are displayed in the list, you can use the ->limitList() method:

RecordFinder::make('products')
    ->multiple()
    ->limitList(3)

This will only display the first 3 selected records. Any further remaining records are hidden. In case there are more items than can be displayed, it will show a text "and x more" at the end of the list.

If you want to show a "show more" link, you can use the ->expandableLimitedList() option:

RecordFinder::make('products')
    ->multiple()
    ->limitList(3)
    ->expandableLimitedList()

If there are more items than can be displayed, it will show a link button "Show X more" that you can click on to display all items. When all items are shown, a "Show X less" button is visible to collapse the items again.

Displaying records as badge

Sometimes it can be nice to display selected records as a badge (or a list of multiple badges). You can do so by using the ->badge() method:

RecordFinder::make('product_id')
    ->badge(),

You can also determine the badge color using the ->badgeColor() method:

RecordFinder::make('product_id')
    ->badge()
    ->badgeColor('gray'),

Alternatively, badge colors can also be determined using a closure based on the selected record that the badge is for:

RecordFinder::make('products')
    ->multiple()
    ->badge()
    ->badgeColor(fn (Product $product) => $product->stock_count ? 'success' : 'danger'),

You can also provide a custom badge icon and determine the icon position:

use Filament\Support\Enums\IconPosition;
use Filament\Support\Icons\Heroicon;

RecordFinder::make('products')
    ->multiple()
    ->badge()
    ->badgeIcon(fn (Product $state) => match ($state->type) {
        ProductType::Product => Heroicon::Cube,
        ProductType::ProductBundle => Heroicon::RectangleGroup,
    })
    ->badgeIconPosition(IconPosition::After),

Changing alignment

By default, lists and text will align at the left side. You can change the alignment by using the available alignment methods:

RecordFinder::make('products')
    ->multiple()
    ->alignLeft()
    ->alignCenter()
    ->alignRight()

Setting a placeholder

By default, the Record Finder will show a placeholder "No item selected yet". If you want to override this, you can set a placeholder for the Record Finder using the ->placeholder() method:

RecordFinder::make('product_id')
    ->placeholder('Click the button to select a product...')

Customizing the modal

The Record Finder Pro plugin gives you full flexibility to customize the modal that opens with the table with records.

Setting the open modal button

By default, the Record Finder will show a button to open the modal/slide-over. The label of the button will be "Select :modelLabel" or "Select :pluralModelLabel" (for multiple) by default. You can customize the label by using the ->openModalActionLabel() method.

By default, the model label is automatically determined based on the following order:

1. If a custom model label is set using ->modelLabel()/->pluralModelLabel(), use that. An example is below.
2. If the component is used in a panel, check if there is a resource for the model. If so, use the resource's getModelLabel()/getPluralModelLabel() methods.
3. Automatically determine the model label based on the field name. For example, the field name some_author_id turns into some author as model label.

You can also set a custom color and icon using the ->openModalActionColor() and ->openModalActionIcon() methods:

use Filament\Support\Icons\Heroicon;

RecordFinder::make('product_id')
    ->openModalActionLabel('Search product')
    ->openModalActionColor('gray')
    ->openModalActionIcon(Heroicon::OutlinedLink)

If you want to customize other attributes of the button, use the methods described below or use the ->openModalAction() method to provide a closure to manually modify the action (see below).

Customizing the modal heading

By default, the Record Finder modal will have a heading similar to "Select author"/"Select authors", depending on whether or not the Record Finder is set to multiple. You can use the ->openModalActionModalHeading() (or alias: ->modalHeading()) methods to customize the heading:

RecordFinder::make('user_id')
    ->openModalActionModalHeading('Select a new admin user')

Customizing the modal description

You can set a custom modal description using the ->openModalActionModalDescription() (or alias ->modalDescription()) methods:

RecordFinder::make('user_id')
    ->openModalActionModalDescription('Use the search bar and/or filters to narrow the selection.')

Using a slide-over instead of a modal

By default, the modal that opens will be a modal. However, you can also turn it into a slide-over modal by using the ->openModalActionSlideOver() (or alias ->slideOver()) method:

RecordFinder::make('user_id')
    ->openModalActionSlideOver()

Customizing the modal width

Depending on how many columns you have in your table, you can customize the width of the modal or slide-over by using the ->openModalActionModalWidth() (or alias ->modalWidth()) method:

use Filament\Support\Enums\MaxWidth;

RecordFinder::make('user_id')
    ->openModalActionModalWidth(MaxWidth::TwoExtraLarge)

Customizing the open modal action

You can also customize the full action by providing a closure to the ->openModalAction() method. This can be very useful if you want to change the look-and-feel of the button. For example, you could add an icon, change the color, use a link-style button, etc. For example, the following will show the button as a link:

use Filament\Support\Icons\Heroicon;

RecordFinder::make('user_id')
    ->hiddenLabel()  // Hide the field label above the button...
    ->openModalAction(function (Action $action) {
        return $action->link()->icon(Heroicon::OutlinedLink);
    })
    ->openModalActionLabel('Select user')

Customizing submit modal button label

Each modal with a table will have a submit button to confirm the current selection. By default, the label will be "Choose". You can customize the label of the submit button using the ->openModalActionModalSubmitActionLabel() (or alias ->modalSubmitActionLabel()) method:

RecordFinder::make('user_id')
    ->openModalActionModalSubmitActionLabel('Confirm')

Customizing model label

If you want, you can provide a custom model label using the ->modelLabel() method:

RecordFinder::make('author_id')
    ->modelLabel('writer')

The plural model label is automatically determined by pluralizing the singular model label. However, if that doesn't work for your case, you can still override the plural model label using the ->pluralModelLabel() method:

RecordFinder::make('author_id')
    ->pluralModelLabel('writers')

Inline layout

By default, the button to select new records will be displayed below the current selection. You can enable an inline layout using the ->inline() method, which brings the button and the selection on the same line:

RecordFinder::make('product_id')
    ->inline()

The label of the field will still stay on top of the field. You can use the ->inlineLabel() to achieve an inline label as well:

RecordFinder::make('product_id')
    ->inline()
    ->inlineLabel()

Table actions & relation managers

Attach action

You can include the RecordFinderAttachAction on your relation manager in the ->headerActions() method to allow attaching new records to your BelongsToMany relationship:

public function table(Table $table): Table
{
    // Within a relation manager...
    return $table
         ->headerActions([
            RecordFinderAttachAction::make()
                ->multiple(),
        ])
        // ...
}

The action works in exactly the same way as the Filament\Tables\Actions\AttachAction::make() class.

The attach action works by guessing the inverse relationship name. In case you are getting an error when attaching a record, provide the inverse relationship name yourself using $table->inverseRelationship('...').

The shown record finder will populate its table columns in the same way as the form component. As a reminder, if there is a resource in your application for the model that is being queried, then the table configuration from the resource will be used. Otherwise, the table columns will be empty.

You can use the ->tableColumns() method in order to add or override the shown columns:

RecordFinderAttachAction::make()
    ->tableColumns([
        Tables\Columns\TextColumn::make('name')
            ->searchable(),
        // ...
    ])

In addition, all other methods available on the RecordFinder component are available here:

If you want to customize the query that is used to populate the table, you can use the ->recordFinderTableQuery() method:

RecordFinderAttachAction::make()
    ->recordFinderTableQuery(function (Builder $query) {
        // return $query->where('type', ...);
    })

If you want to pre-select certain records in the table on opening, you can use the ->defaultState() method:

RecordFinderAttachAction::make()
    ->defaultState(User::find(999))

Associate action

You can include the RecordFinderAssociateAction on your relation manager in the ->headerActions() method to allow associating new records to your HasMany or MorphMany relationship:

public function table(Table $table): Table
{
    // Within a relation manager...
    return $table
         ->headerActions([
            RecordFinderAssociateAction::make()
                ->multiple(),
        ])
        // ...
}

The action works in exactly the same way as the Filament\Tables\Actions\AssociateAction::make() class.

The associate action works by guessing the inverse relationship name. In case you are getting an error when associating a record, provide the inverse relationship name yourself using $table->inverseRelationship('...').

The RecordFinderAssociateAction has the same methods & options as the above RecordFinderAttachAction.