Forms Documentation

Appearance

Model Binding ​

Model binding populates a form with data from an Eloquent model. Call bind() with a model instance, and each field's value is filled from the corresponding model attribute.

Basic Binding ​

php
use App\Forms\EditUserForm;

class UserController
{
    public function edit(User $user)
    {
        return Inertia::render('Users/Edit', [
            'form' => EditUserForm::make()->bind($user),
        ]);
    }
}

The form automatically reads the model's attributes and uses them as the initial field values.

Skipping Bound Values ​

Use withoutModelBinding() when a declared field should still render, submit, and validate normally, but should not read its initial value from the bound model:

php
TextInput::make('api_token')
    ->withoutModelBinding()
    ->required();

Password text inputs call withoutModelBinding() by default. This keeps stored password hashes out of the serialized form data on edit screens:

php
TextInput::make('password')->password();

For forms with several sensitive fields, pass an exclusion list to bind():

php
EditUserForm::make()->bind($user, except: [
    'password',
    'api_token',
]);

The except list only affects model hydration for matching declared field names. It does not remove fields from the form and does not change submission or validation.

If an application truly needs to hydrate a password field from the model, opt in deliberately:

php
TextInput::make('temporary_password')
    ->password()
    ->withModelBinding();

Binding Lookup Order ​

Bound models and arrays are read with Laravel's data_get() helper. The field name is the lookup path, and default() is used only when that path is missing. Only values for fields declared by the form are serialized. Binding a model does not send the full model or unused attributes to the frontend.

Field names therefore support dot notation for nested data:

php
TextInput::make('address.city'),    // data_get($model, 'address.city')
TextInput::make('settings.theme'),  // data_get($model, 'settings.theme')

Default Values ​

Without a bound model, or without a value at the bound path, the field falls back to its default value:

php
TextInput::make('nickname')->default('Anonymous'),
Combobox::make('theme')->options([...])->default('light'),
Toggle::make('notifications')->default(true),

Without bind(), base field value resolution starts from each field's default value (which is null unless set with default()). Field types such as Checkbox and Toggle may then normalize that value.

A bound attribute with a null value makes data_get() return null. The field does not replace that value with default().

Works with Eloquent Features ​

Binding reads values through the model, so normal Eloquent behavior applies. Accessors may provide field values, casts return their cast values before the field normalizes them, and JSON or array casts can be read with dot notation.

data_get() also follows relationship accessors, so you may bind to related model data such as a profile field.

Eager-load relations used by field names when you want predictable query behavior. Eloquent may lazy-load an unloaded relationship during binding. Prevented lazy loading or a missing relation resolves the value to null.

Binding Arrays ​

You may also bind an array instead of a model:

php
$form = EditSettingsForm::make()->bind([
    'site_name' => 'My App',
    'contact_email' => 'admin@example.com',
    'features' => [
        'registration' => true,
        'dark_mode' => false,
    ],
]);

This is useful for forms that do not map directly to an Eloquent model, like settings pages or config editors.

Edit Forms ​

bind() fills the form with model values. It does not change where the form submits. For edit screens, set the action route on the same form instance:

php
EditUserForm::make()
    ->bind($user)
    ->route('users.update', ['user' => $user]);

Route parameters may include the model. The form's HTTP method is still detected from the named route definition.

Checkbox and Toggle Binding ​

The Checkbox and Toggle fields preserve bound or default values that exactly match their configured checked/on or unchecked/off values. Other values fall back to their boolean meaning so boolean-backed attributes hydrate predictably:

php
// If $user->is_admin is truthy, the toggle returns its on value
Toggle::make('is_admin'),

// Custom values
Checkbox::make('status')
    ->trueValue('active')
    ->falseValue('inactive'),
// "active" and "inactive" are preserved exactly. Other values use the
// truthiness fallback and return the configured true or false value.

File Field Binding ​

The File field converts bound values to existing file representations. Model file path strings become preview-friendly objects. With Spatie Media Library integration, media items are loaded from the specified collection:

php
File::make('avatar')->image(),
// Reads the file path from $user->avatar and creates a preview URL

File::make('documents')
    ->multiple()
    ->mediaCollection('documents'),
// Loads media from $user->getMedia('documents')