Key-value

import AutoScreenshot from "@components/AutoScreenshot.astro" import UtilityInjection from "@components/UtilityInjection.astro"

Introduction¶

The key-value field allows you to interact with one-dimensional JSON object:

use Filament\Forms\Components\KeyValue;

KeyValue::make('meta')

If you're saving the data in Eloquent, you should be sure to add an array cast to the model property:

use Illuminate\Database\Eloquent\Model;

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

    // ...
}

Adding rows¶

An action button is displayed below the field to allow the user to add a new row.

Setting the add action button's label¶

You may set a label to customize the text that should be displayed in the button for adding a row, using the addActionLabel() method:

use Filament\Forms\Components\KeyValue;

KeyValue::make('meta')
    ->addActionLabel('Add property')

As well as allowing a static value, the addActionLabel() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Preventing the user from adding rows¶

You may prevent the user from adding rows using the addable(false) method:

use Filament\Forms\Components\KeyValue;

KeyValue::make('meta')
    ->addable(false)

As well as allowing a static value, the addable() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Deleting rows¶

An action button is displayed on each item to allow the user to delete it.

Preventing the user from deleting rows¶

You may prevent the user from deleting rows using the deletable(false) method:

use Filament\Forms\Components\KeyValue;

KeyValue::make('meta')
    ->deletable(false)

As well as allowing a static value, the deletable() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Editing keys¶

Customizing the key fields' label¶

You may customize the label for the key fields using the keyLabel() method:

use Filament\Forms\Components\KeyValue;

KeyValue::make('meta')
    ->keyLabel('Property name')

As well as allowing a static value, the keyLabel() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Adding key field placeholders¶

You may also add placeholders for the key fields using the keyPlaceholder() method:

use Filament\Forms\Components\KeyValue;

KeyValue::make('meta')
    ->keyPlaceholder('Property name')

As well as allowing a static value, the keyPlaceholder() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Preventing the user from editing keys¶

You may prevent the user from editing keys using the editableKeys(false) method:

use Filament\Forms\Components\KeyValue;

KeyValue::make('meta')
    ->editableKeys(false)

As well as allowing a static value, the editableKeys() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Editing values¶

Customizing the value fields' label¶

You may customize the label for the value fields using the valueLabel() method:

use Filament\Forms\Components\KeyValue;

KeyValue::make('meta')
    ->valueLabel('Property value')

As well as allowing a static value, the valueLabel() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Adding value field placeholders¶

You may also add placeholders for the value fields using the valuePlaceholder() method:

use Filament\Forms\Components\KeyValue;

KeyValue::make('meta')
    ->valuePlaceholder('Property value')

As well as allowing a static value, the valuePlaceholder() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Preventing the user from editing values¶

You may prevent the user from editing values using the editableValues(false) method:

use Filament\Forms\Components\KeyValue;

KeyValue::make('meta')
    ->editableValues(false)

As well as allowing a static value, the editableValues() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Reordering rows¶

You can allow the user to reorder rows within the table using the reorderable() method:

use Filament\Forms\Components\KeyValue;

KeyValue::make('meta')
    ->reorderable()

As well as allowing a static value, the reorderable() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Customizing the key-value 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. The following methods are available to customize the actions:

addAction()
deleteAction()
reorderAction()

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

use Filament\Actions\Action;
use Filament\Forms\Components\KeyValue;
use Filament\Support\Icons\Heroicon;

KeyValue::make('meta')
    ->deleteAction(
        fn (Action $action) => $action->icon(Heroicon::XMark),
    )

The action registration methods can inject various utilities into the function as parameters.