Builder - Forms - Filament

Introduction

Similar to a repeater, the builder component allows you to output a JSON array of repeated form components. Unlike the repeater, which only defines one form schema to repeat, the builder allows you to define different schema “blocks”, which you can repeat in any order. This makes it useful for building more advanced array structures.

The primary use of the builder component is to build web page content using predefined blocks. This could be content for a marketing website, or maybe even fields in an online form. The example below defines multiple blocks for different elements in the page content. On the frontend of your website, you could loop through each block in the JSON and format it how you wish.

use Filament\Forms\Components\Builder;
use Filament\Forms\Components\Builder\Block;
use Filament\Forms\Components\FileUpload;
use Filament\Forms\Components\Select;
use Filament\Forms\Components\Textarea;
use Filament\Forms\Components\TextInput;

Builder::make('content')
    ->blocks([
        Block::make('heading')
            ->schema([
                TextInput::make('content')
                    ->label('Heading')
                    ->required(),
                Select::make('level')
                    ->options([
                        'h1' => 'Heading 1',
                        'h2' => 'Heading 2',
                        'h3' => 'Heading 3',
                        'h4' => 'Heading 4',
                        'h5' => 'Heading 5',
                        'h6' => 'Heading 6',
                    ])
                    ->required(),
            ])
            ->columns(2),
        Block::make('paragraph')
            ->schema([
                Textarea::make('content')
                    ->label('Paragraph')
                    ->required(),
            ]),
        Block::make('image')
            ->schema([
                FileUpload::make('url')
                    ->label('Image')
                    ->image()
                    ->required(),
                TextInput::make('alt')
                    ->label('Alt text')
                    ->required(),
            ]),
    ])

We recommend that you store builder data with a JSON column in your database. Additionally, if you’re using Eloquent, make sure that column has an array cast.

As evident in the above example, blocks can be defined within the blocks() method of the component. Blocks are Builder\Block objects, and require a unique name, and a component schema:

use Filament\Forms\Components\Builder;
use Filament\Forms\Components\Builder\Block;
use Filament\Forms\Components\TextInput;

Builder::make('content')
    ->blocks([
        Block::make('heading')
            ->schema([
                TextInput::make('content')->required(),
                // ...
            ]),
        // ...
    ])

Setting a block’s label

By default, the label of the block will be automatically determined based on its name. To override the block’s label, you may use the label() method. Customizing the label in this way is useful if you wish to use a translation string for localization:

use Filament\Forms\Components\Builder\Block;

Block::make('heading')
    ->label(__('blocks.heading'))

Labelling builder items based on their content

You may add a label for a builder item using the same label() method. This method accepts a closure that receives the item’s data in a $state variable. If $state is null, you should return the block label that should be displayed in the block picker. Otherwise, you should return a string to be used as the item label:

use Filament\Forms\Components\Builder\Block;
use Filament\Forms\Components\TextInput;

Block::make('heading')
    ->schema([
        TextInput::make('content')
            ->live(onBlur: true)
            ->required(),
        // ...
    ])
    ->label(function (?array $state): string {
        if ($state === null) {
            return 'Heading';
        }

        return $state['content'] ?? 'Untitled heading';
    })

Any fields that you use from $state should be live() if you wish to see the item label update live as you use the form.

You can inject various utilities into the function passed to label() as parameters.

Utility	Type	Parameter	Description
Field	`Filament\Forms\Components\Field`	`$component`	The current field component instance.
Get function	`Filament\Schemas\Components\Utilities\Get`	`$get`	A function for retrieving values from the current form data. Validation is not run.
Key	`string`	`$key`	The key for the current block.
Livewire	`Livewire\Component`	`$livewire`	The Livewire component instance.
Eloquent model FQN	`?string<Illuminate\Database\Eloquent\Model>`	`$model`	The Eloquent model FQN for the current schema.
Operation	`string`	`$operation`	The current operation being performed by the schema. Usually `create`, `edit`, or `view`.
Raw state	`mixed`	`$rawState`	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	`?Illuminate\Database\Eloquent\Model`	`$record`	The Eloquent record for the current schema.
State	`array<string, mixed>`	`$state`	The raw unvalidated data for the current block.

Utility	Type	Parameter	Description
Action	`Filament\Actions\Action`	`$action`	The action object to customize.
Field	`Filament\Forms\Components\Field`	`$component`	The current field component instance.
Get function	`Filament\Schemas\Components\Utilities\Get`	`$get`	A function for retrieving values from the current form data. Validation is not run.
Livewire	`Livewire\Component`	`$livewire`	The Livewire component instance.
Eloquent model FQN	`?string<Illuminate\Database\Eloquent\Model>`	`$model`	The Eloquent model FQN for the current schema.
Operation	`string`	`$operation`	The current operation being performed by the schema. Usually `create`, `edit`, or `view`.
Raw state	`mixed`	`$rawState`	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	`?Illuminate\Database\Eloquent\Model`	`$record`	The Eloquent record for the current schema.
State	`mixed`	`$state`	The current value of the field. Validation is not run.

#Introduction

#Setting a block’s label

#Labelling builder items based on their content

#Numbering builder items

#Setting a block’s icon

#Adding icons to the header of blocks

#Previewing blocks

#Interactive block previews

#Adding items

#Setting the add action button’s label

#Aligning the add action button

#Preventing the user from adding items

#Deleting items

#Preventing the user from deleting items

#Reordering items

#Preventing the user from reordering items

#Reordering items with buttons

#Preventing reordering with drag and drop

#Collapsing items

#Cloning items

#Customizing the block picker

#Changing the number of columns in the block picker

#Increasing the width of the block picker

#Limiting the number of times a block can be used

#Using $get() to access parent field values

#Builder validation

#Number of items validation

#Customizing the builder item actions

#Confirming builder actions with a modal

#Adding extra item actions to a builder

Introduction

Setting a block’s label

Labelling builder items based on their content

Numbering builder items

Setting a block’s icon

Adding icons to the header of blocks

Previewing blocks

Interactive block previews

Adding items

Setting the add action button’s label

Aligning the add action button

Preventing the user from adding items

Deleting items

Preventing the user from deleting items

Reordering items

Preventing the user from reordering items

Reordering items with buttons

Preventing reordering with drag and drop

Collapsing items

Cloning items

Customizing the block picker

Changing the number of columns in the block picker

Increasing the width of the block picker

Limiting the number of times a block can be used

Using `$get()` to access parent field values

Builder validation

Number of items validation

Customizing the builder item actions

Confirming builder actions with a modal

Adding extra item actions to a builder