filament/packages/forms/docs/03-fields/01-getting-started.md

title

title
Getting started

Field classes can be found in the Filament\Form\Components namespace.

Fields reside within the schema of your form, alongside any layout components.

If you're using the fields in a Livewire component, you can put them in the getFormSchema() method:

protected function getFormSchema(): array
{
    return [
        // ...
    ];
}

If you're using them in admin panel resources or relation managers, you must put them in the $form->schema() method:

public static function form(Form $form): Form
{
    return $form
        ->schema([
            // ...
        ]);
}

Fields may be created using the static make() method, passing its name. The name of the field should correspond to a property on your Livewire component. You may use Livewire's "dot syntax" to bind fields to nested properties such as arrays and Eloquent models.

use Filament\Forms\Components\TextInput;

TextInput::make('name')

Setting a label

By default, the label of the field will be automatically determined based on its name. To override the field'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\TextInput;

TextInput::make('name')->label(__('fields.name'))

Optionally, you can have the label automatically translated by using the translateLabel() method:

use Filament\Forms\Components\TextInput;

TextInput::make('name')->translateLabel() // Equivalent to `label(__('Name'))`

Setting an ID

In the same way as labels, field IDs are also automatically determined based on their names. To override a field ID, use the id() method:

use Filament\Forms\Components\TextInput;

TextInput::make('name')->id('name-field')

Setting a default value

Fields may have a default value. This will be filled if the form's fill() method is called without any arguments. To define a default value, use the default() method:

use Filament\Forms\Components\TextInput;

TextInput::make('name')->default('John')

Note that inside the admin panel this only works on Create Pages, as Edit Pages will always fill the data from the model.

Helper messages and hints

Sometimes, you may wish to provide extra information for the user of the form. For this purpose, you may use helper messages and hints.

Help messages are displayed below the field. The helperText() method supports Markdown formatting:

use Filament\Forms\Components\TextInput;

TextInput::make('name')->helperText('Your full name here, including any middle names.')

Hints can be used to display text adjacent to its label:

use Filament\Forms\Components\TextInput;

TextInput::make('password')->hint('[Forgotten your password?](forgotten-password)')

Hints may also have an icon rendered next to them:

use Filament\Forms\Components\RichEditor;

RichEditor::make('content')
    ->hint('Translatable')
    ->hintIcon('heroicon-m-language')

Hints may have a color(). By default it's gray, but you may use primary, success, warning, or danger:

use Filament\Forms\Components\RichEditor;

RichEditor::make('content')
    ->hint('Translatable')
    ->hintColor('primary')

Custom attributes

The HTML attributes of the field's wrapper can be customized by passing an array of extraAttributes():

use Filament\Forms\Components\TextInput;

TextInput::make('name')->extraAttributes(['title' => 'Text input'])

To add additional HTML attributes to the input itself, use extraInputAttributes():

use Filament\Forms\Components\TextInput;

TextInput::make('points')
    ->numeric()
    ->extraInputAttributes(['step' => '10'])

Disabling

You may disable a field to prevent it from being edited:

use Filament\Forms\Components\TextInput;

TextInput::make('name')->disabled()

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

use Filament\Forms\Components\Toggle;

Toggle::make('is_admin')->disabled(! auth()->user()->isAdmin())

Please note that disabling a field does not prevent it from being saved, and a skillful user could manipulate the HTML of the page and alter its value.

To prevent a field from being saved, use the dehydrated(false) method:

Toggle::make('is_admin')->dehydrated(false)

Alternatively, you may only want to save a field conditionally, maybe if the user is an admin:

Toggle::make('is_admin')
    ->disabled(! auth()->user()->isAdmin())
    ->dehydrated(auth()->user()->isAdmin())

If you're using the admin panel and only want to save disabled fields on the Create page of a resource:

use Filament\Resources\Pages\CreateRecord;
use Filament\Resources\Pages\Page;

TextInput::make('slug')
    ->disabled()
    ->dehydrated(fn (Page $livewire) => $livewire instanceof CreateRecord)

Autofocusing

Most fields will be autofocusable. Typically, you should aim for the first significant field in your form to be autofocused for the best user experience.

use Filament\Forms\Components\TextInput;

TextInput::make('name')->autofocus()

Setting a placeholder

Many fields will also include a placeholder value for when it has no value. You may customize this using the placeholder() method:

use Filament\Forms\Components\TextInput;

TextInput::make('name')->placeholder('John Doe')

Marking as required

By default, required fields will show an asterisk (*) next to their label. You may want to hide the asterisk on forms with only required fields, or where it makes sense to add a hint to optional fields instead:

use Filament\Forms\Components\TextInput;

TextInput::make('name')
    ->required()
    ->markAsRequired(false)

Global settings

If you wish to change the default behaviour of a field globally, then you can call the static configureUsing() method inside a service provider's boot() method, to which you pass a Closure to modify the component using. For example, if you wish to make all checkboxes inline(false), you can do it like so:

use Filament\Forms\Components\Checkbox;

Checkbox::configureUsing(function (Checkbox $checkbox): void {
    $checkbox->inline(false);
});

Of course, you are still able to overwrite this on each field individually:

use Filament\Forms\Components\Checkbox;

Checkbox::make('is_admin')->inline()