Getting started
Field classes can be found in theFilament\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:
$form->schema() method:
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.
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 thelabel() method. Customizing the label in this way is useful if you wish to use a translation string for localization:
translateLabel() method:
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 theid() method:
Setting a default value
Fields may have a default value. This will be filled if the form’sfill() method is called without any arguments. To define a default value, use the default() method:
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. ThehelperText() method supports Markdown formatting:
color(). By default it’s gray, but you may use primary, success, warning, or danger:
Custom attributes
The HTML attributes of the field’s wrapper can be customized by passing an array ofextraAttributes():
extraInputAttributes():
Disabling
You may disable a field to prevent it from being edited:dehydrated(false) method:
Hiding
You may hide a field: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.Setting a placeholder
Many fields will also include a placeholder value for when it has no value. You may customize this using theplaceholder() method:
Global settings
If you wish to change the default behaviour of a field globally, then you can call the staticconfigureUsing() 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:
Text input
The text input allows you to interact with a string:
You may set the type of string using a set of methods. Some, such as email(), also provide validation:
type() method to pass another HTML input type:
minLength() and maxLength() methods. These methods add both frontend and backend validation:
length(). This method adds both frontend and backend validation:
minValue() and maxValue() methods:
autocomplete() method:
autocomplete="off", you may disableAutocomplete():
Phone number validation
When using atel() field, the value will be validated using: /^[+]*[(]{0,1}[0-9]{1,4}[)]{0,1}[-\s\.\/0-9]*$/.
If you wish to change that, then you can use the telRegex() method:
telRegex() across all fields, use a service provider:
Affixes
You may place text before and after the input using theprefix() and suffix() methods:
You may place a icon before and after the input using the prefixIcon() and suffixIcon() methods:
prefixAction() and suffixAction() methods:
Input masking
Input masking is the practice of defining a format that the input value must conform to. In Filament, you may interact with theMask object in the mask() method to configure your mask:
imaskjs. The vast majority of its masking features are also available in Filament. Reading their guide first, and then approaching the same task using Filament is probably the easiest option.
You may define and configure a numeric mask to deal with numbers:
money() method that is able to define easier formatting for currency inputs. This example, the symbol prefix is €, there is a , thousands separator, and two decimal places:
isSigned: false allows only positive numbers:
Datalists
You may specify datalist options for a text input using thedatalist() method:
Datalists provide autocomplete options to users when they use a text input. However, these are purely recommendations, and the user is still able to type any value into the input. If you’re looking for strictly predefined options, check out select fields.
Select
The select component allows you to select from a list of predefined options:options() array, the array keys are saved, and the array values will be the label of each option in the dropdown.
You may enable a search input to allow easier access to many options, using the searchable() method:
If you have lots of options and want to populate them based on a database search or other external data source, you can use the getSearchResultsUsing() and getOptionLabelUsing() methods instead of options().
The getSearchResultsUsing() method accepts a callback that returns search results in $key => $value format.
The getOptionLabelUsing() method accepts a callback that transforms the selected option $value into a label.
disablePlaceholderSelection() method:
Multi-select
Themultiple() method on the Select component allows you to select multiple values from the list of options:
These options are returned in JSON format. If you’re saving them using Eloquent, you should be sure to add an array cast to the model property:
getOptionLabelUsing(), the getOptionLabelsUsing() method can be used to transform the selected options’ $values into labels.
Dependant selects
Commonly, you may desire “dependant” select inputs, which populate their options based on the state of another.
Some of the techniques described in the advanced forms section are required to create dependant selects. These techniques can be applied across all form components for many dynamic customization possibilities.
Populating automatically from a relationship
You may employ therelationship() method of the Select to configure a BelongsTo relationship to automatically retrieve and save options from:
multiple() method may be used in combination with relationship() to automatically populate from a BelongsToMany relationship:
To set this functionality up, you must also follow the instructions set out in the field relationships section. If you’re using the admin panel, you can skip this step.If you’d like to populate the options from the database when the page is loaded, instead of when the user searches, you can use the
preload() method:
relationship() method:
getOptionLabelFromRecordUsing() method to transform the selected option’s Eloquent model into a label. But please note, this is much less performant than using a virtual column:
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:
titleColumnName() is used to extract the titles out of each product or post. You can choose to extract the option labels using getOptionLabelFromRecordUsing instead if you wish:
modifyOptionsQueryUsing() method:
Many of the same options in the select field are available forMorphToSelect, includingsearchable(),preload(),allowHtml(), andoptionsLimit().
Creating new records
You may define a custom form that can be used to create a new record and attach it to theBelongsTo relationship:
<form> elements, you must also render the modal outside the <form> in the view. If you’re using the admin panel, this is included already:
Checkbox
The checkbox component, similar to a toggle, allows you to interact a boolean value.
Checkbox fields have two layout modes, inline and stacked. By default, they are inline.
When the checkbox is inline, its label is adjacent to it:
When the checkbox is stacked, its label is above it:
If you’re saving the boolean value using Eloquent, you should be sure to add a boolean cast to the model property:
Toggle
The toggle component, similar to a checkbox, allows you to interact a boolean value.
Toggle fields have two layout modes, inline and stacked. By default, they are inline.
When the toggle is inline, its label is adjacent to it:
When the toggle is stacked, its label is above it:
Toggles may also use an “on icon” and an “off icon”. These are displayed on its handle and could provide a greater indication to what your field represents. The parameter to each method must contain the name of a Blade icon component:
primary, secondary, success, warning or danger:
If you’re saving the boolean value using Eloquent, you should be sure to add a boolean cast to the model property:
Checkbox list
The checkbox list component allows you to select multiple values from a list of predefined options:
These options are returned in JSON format. If you’re saving them using Eloquent, you should be sure to add an array cast to the model property:
columns() method:
This method accepts the same options as the columns() method of the grid. This allows you to responsively customize the number of columns at various breakpoints.
You may also allow users to toggle all checkboxes at once using the bulkToggleable() method:
Populating automatically from a relationship
You may employ therelationship() method to configure a relationship to automatically retrieve and save options from:
To set this functionality up, you must also follow the instructions set out in the field relationships section. If you’re using the admin panel, you can skip this step.You may customize the database query that retrieves options using the third parameter of the
relationship() method:
getOptionLabelFromRecordUsing() method to transform the selected option’s Eloquent model into a label. But please note, this is much less performant than using a virtual column:
Radio
The radio input provides a radio button group for selecting a single value from a list of predefined options:
You can optionally provide descriptions to each option using the descriptions() method:
Be sure to use the same key in the descriptions array as the key in the options array so the right description matches the right option.
If you want a simple boolean radio button group, with “Yes” and “No” options, you can use the boolean() method:
You may wish to display the options inline() with the label:
Date-time picker
The date-time picker provides an interactive interface for selecting a date and a time.
You may restrict the minimum and maximum date that can be selected with the picker. The minDate() and maxDate() methods accept a DateTime instance (e.g. Carbon), or a string:
You may customize the format of the field when it is saved in your database, using the format() method. This accepts a string date format, using PHP date formatting tokens:
displayFormat() method, which also accepts a string date format, using PHP date formatting tokens:
When using the time picker, you may disable the seconds input using the withoutSeconds() method:
hoursStep() , minutesStep() or secondsStep() methods:
In some countries, the first day of the week is not Monday. To customize the first day of the week in the date picker, use the forms.components.date_time_picker.first_day_of_week config option, or the firstDayOfWeek() method on the component. 0 to 7 are accepted values, with Monday as 1 and Sunday as 7 or 0:
There are additionally convenient helper methods to set the first day of the week more semantically:
icon() method:
false:
Timezones
If you’d like users to be able to manage dates in their own timezone, you can use thetimezone() method:
File upload
The file upload field is based on Filepond.
By default, files will be uploaded publicly to your default storage disk.
Please note, to correctly preview images and other files, FilePond requires files to be served from the same domain as the app, or the appropriate CORS headers need to be present. Ensure that the APP_URL environment variable is correct, or modify the filesystem driver to set the correct URL. If you’re hosting files on a separate domain like S3, ensure that CORS headers are set up.
To change the disk and directory that files are saved in, and their visibility, use the disk(), directory() and visibility methods:
Please note, it is the responsibility of the developer to delete these files from the disk if they are removed, as Filament is unaware if they are depended on elsewhere. One way to do this automatically is observing a model event.By default, a random file name will be generated for newly-uploaded files. To instead preserve the original filenames of the uploaded files, use the
preserveFilenames() method:
getUploadedFileNameForStorageUsing() method, and returning a string from the callback:
storeFileNamesIn() method:
attachment_file_names will now store the original file name/s of your uploaded files.
You may restrict the types of files that may be uploaded using the acceptedFileTypes() method, and passing an array of MIME types. You may also use the image() method as shorthand to allow all image MIME types.
To customize Livewire’s default file upload validation rules, including the 12MB file size maximum, please refer to its documentation.Filepond allows you to crop and resize images before they are uploaded. You can customize this behaviour using the
imageResizeMode(), imageCropAspectRatio(), imageResizeTargetHeight() and imageResizeTargetWidth() methods. imageResizeMode() should be set for the other methods to have an effect - either force, cover, or contain.
You may also upload multiple files. This stores URLs in JSON:
array cast to the model property:
minFiles() and maxFiles() methods:
enableReordering() method:
enableOpen() method:
enableDownload() method:
Filament also supports spatie/laravel-medialibrary. See our plugin documentation for more information.
Rich editor
The rich editor allows you to edit and preview HTML content, as well as upload images.
You may enable / disable toolbar buttons using a range of convenient methods:
Markdown editor
The markdown editor allows you to edit and preview markdown content, as well as upload images using drag and drop.
You may enable / disable toolbar buttons using a range of convenient methods:
Hidden
The hidden component allows you to create a hidden field in your form that holds a value.Repeater
The repeater component allows you to output a JSON array of repeated form components.
We recommend that you store repeater 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, the component schema can be defined within the schema() method of the component:
defaultItems() method:
You may also prevent the user from adding items, deleting items, or moving items inside the repeater:
minItems() and maxItems() methods:
Collapsible
The repeater may becollapsible() to optionally hide content in long forms:
Cloning items
You may allow repeater items to be duplicated using thecloneable() method:
Populating automatically from a relationship
You may employ therelationship() method of the repeater to configure a relationship to automatically retrieve and save repeater items:
To set this functionality up, you must also follow the instructions set out in the field relationships section. If you’re using the admin panel, you can skip this step.
Ordering items
By default, ordering relationship repeater items is disabled. This is because your related model needs ansort column to store the order of related records. To enable ordering, you may use the orderable() method:
sort column.
If you use something like spatie/eloquent-sortable with an order column such as order_column, you may pass this in to orderable():
Grid layout
You may organize repeater items into columns by using thegrid() method:
columns() method of the grid. This allows you to responsively customize the number of grid columns at various breakpoints.
Item labels
You may add a label for repeater items using theitemLabel() method:
$state should be reactive() or lazy() if you wish to see the item label update live as you use the form.
Using $get() to access parent field values
All form components are able to use $get() and $set() to access another field’s value. However, you might experience unexpected behaviour when using this inside the repeater’s schema.
This is because $get() and $set(), by default, are scoped to the current repeater item. This means that you are able to interact with another field inside that repeater item easily without knowing which repeater item the current form component belongs to.
The consequence of this, is that you may be confused when you are unable to interact with a field outside the repeater. We use ../ syntax to solve this problem - $get('../../parent_field_name').
Consider your form has this data structure:
client_id from inside the repeater item.
$get() is relative to the current repeater item, so $get('client_id') is looking for $get('repeater.item1.client_id').
You can use ../ to go up a level in the data structure, so $get('../client_id') is $get('repeater.client_id') and $get('../../client_id') is $get('client_id').
Builder
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. 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.
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:
label() method. Customizing the label in this way is useful if you wish to use a translation string for localization:
icon() method accepts the name of any Blade icon component:
You may customize the number of items that may be created, using the minItems() and maxItems() methods:
Collapsible
The builder may becollapsible() to optionally hide content in long forms:
Tags input
The tags input component allows you to interact with a list of tags. By default, tags are stored in JSON:
If you’re saving the JSON tags using Eloquent, you should be sure to add an array cast to the model property:
separator() method:
suggestions() method:
Filament also supports spatie/laravel-tags. See our plugin documentation for more information.
Textarea
The textarea allows you to interact with a multi-line string:
You may change the size of the textarea by defining the rows() and cols() methods:
minLength() and maxLength() methods. These methods add both frontend and backend validation:
Key-value
The key-value field allows you to interact with one-dimensional JSON object:
You may customize the labels for the key and value fields using the keyLabel() and valueLabel() methods:
You may also prevent the user from adding rows, deleting rows, or editing keys:
keyPlaceholder() and valuePlaceholder() methods:
Color picker
The color picker component allows you to pick a color in a range of formats. By default, the component uses HEX format:
Alternatively, you can use a different format:
View
Aside from building custom fields, you may create “view” fields which allow you to create custom fields without extra PHP classes.$getStatePath() closure may be used by the view to retrieve the Livewire property path of the field. You could use this to wire:model a value, or $wire.entangle it with Alpine.js.
Using Livewire’s entangle allows sharing state with Alpine.js:
wire:model:
Building custom fields
You may create your own custom field classes and views, which you can reuse across your project, and even release as a plugin to the community.If you’re just creating a simple custom field to use once, you could instead use a view field to render any custom Blade file.To create a custom field class and view, you may use the following command:
$getStatePath() closure may be used by the view to retrieve the Livewire property path of the field. You could use this to wire:model a value, or $wire.entangle it with Alpine.js: