Fields — Complete Reference

Auto-generated from source code. Every agent MUST update this file when adding or modifying fields or base field methods.

All available field types in Martis, their methods, and configuration options.

Table of Contents

• Import
• Base Field (Common Methods)
  • Factory
  • Identity
  • Value Resolution & Filling
  • Fluent Configuration
  • Visibility
  • Granular Visibility
  • Convenience Visibility Presets
  • Context-Aware Visibility
  • Field authorization: canSee() and canSeeForModel()
  • Sortable / Searchable
  • Validation
    • What an update validates
  • Unique Validation
  • Customization Hooks
    • Computed fields
  • Component Override
  • Metadata
  • Serialization
• Tooltips (Martis differential)
• Field Types
  • Id
  • Text
  • Textarea
  • Number
  • Boolean
  • BooleanGroup
  • Avatar
  • UiAvatar
  • Audio
  • Select
  • GuardSelect
  • MultiSelect
  • Date
  • DateTime
  • Email
  • Password
  • PasswordConfirmation
  • Slug
  • Timezone
  • Icon
  • Stack + Line
  • Url
  • Color
  • Country
  • Currency
  • BelongsTo
  • Tag
  • BelongsToMany
  • HasOne
  • HasOneOfMany
  • HasOneThrough
  • HasMany
  • HasManyThrough
  • MorphOne
  • MorphOneOfMany
  • MorphMany
  • MorphTo
  • MorphToMany
  • File
  • Image
  • Code
  • Markdown
  • Trix
  • KeyValue
  • Heading
  • Hidden
  • Badge
  • Badges
  • Status
  • Gravatar
  • Sparkline
• Utility Classes
  • DeferredRelationSync
  • FieldContext (Enum)

Import

use Martis\Fields\Badge;
use Martis\Fields\BelongsTo;
use Martis\Fields\Audio;
use Martis\Fields\Avatar;
use Martis\Fields\Boolean;
use Martis\Fields\BooleanGroup;
use Martis\Fields\Code;
use Martis\Fields\Color;
use Martis\Fields\Country;
use Martis\Fields\Currency;
use Martis\Fields\Date;
use Martis\Fields\DateTime;
use Martis\Fields\Email;
use Martis\Fields\File;
use Martis\Fields\Gravatar;
use Martis\Fields\Heading;
use Martis\Fields\Hidden;
use Martis\Fields\Icon;
use Martis\Fields\Id;
use Martis\Fields\Image;
use Martis\Fields\KeyValue;
use Martis\Fields\Line;
use Martis\Fields\Markdown;
use Martis\Fields\MultiSelect;
use Martis\Fields\Number;
use Martis\Fields\Password;
use Martis\Fields\PasswordConfirmation;
use Martis\Fields\Select;
use Martis\Fields\Slug;
use Martis\Fields\Sparkline;
use Martis\Fields\Stack;
use Martis\Fields\Status;
use Martis\Fields\Tag;
use Martis\Fields\Text;
use Martis\Fields\Textarea;
use Martis\Fields\Timezone;
use Martis\Fields\Trix;
use Martis\Fields\UiAvatar;
use Martis\Fields\Url;

Base Field (Common Methods)

All fields extend Martis\Fields\Field (abstract) which implements Martis\Contracts\FieldContract. These methods are available on every field type.

Factory

Text::make('title')                    // label = "Title"
Text::make('first_name', 'First Name') // explicit label

Identity

Value Resolution & Filling

Structured values and file uploads

A form that uploads a file (a new File / Image was picked) is sent as multipart/form-data, and FormData carries strings and files only. The SPA therefore encodes every non-file value on that path in a shape the server reads back exactly as the JSON request path would send it:

The decoding runs in every resource controller (ResourceController, HasMany / HasOne / MorphMany / MorphOne inline forms) through DecodesStructuredValues, so a Repeater's rows, a MultiSelect's selection, a BooleanGroup's flag map, a KeyValue's pairs, a Tag's ids, a MorphTo's target or a Sparkline's points survive a save that also uploads a file, validation rules such as array / max:N see the real list, and fill() receives the same value it gets on a JSON save.

A value that is not a list or a map is never stored: a non-empty string that does not decode to one ("[object Object]", "12,15", a JSON scalar) on either path, and a number or a boolean a JSON request sends ({"meta": 5, "labels": true}). The controller validates it with Laravel's array rule on top of the field's own rules, so the request fails with a 422 (The <label> field must be an array.) and the stored value stays as it was, whether or not the field declares an array rule. This holds on both request paths for every field whose rejectsUnstructuredValue() is true, so a stale SPA bundle or a hand-written API call cannot empty a Repeater, clear a KeyValue or MultiSelect, detach every Tag or store the text in a BooleanGroup column. It does not apply where no data is at risk: a readonly or computed field writes nothing, a fillUsing() callback decides which shapes it accepts, and a MorphTo ignores any value that is not a target map (an update form up to v1.37.3 sends a bare id for an untouched target, and a morph key can be a string). null and the empty string (what the multipart path sends for null) still clear the field. Since v1.38.0; in v1.37.3 only a field with its own array rule was protected from a string, and nothing stopped a number or a boolean sent on the JSON path from reaching fill() and emptying the field.

Custom fields whose form value is a list or a map should return true from hasStructuredValue() to join that path; a field whose value is a string that happens to look like JSON (a Code editor holding JSON, a Textarea) must leave it false so its text is never decoded.

Before v1.37.3 the multipart body carried String(value) for everything: structured values arrived as "[object Object]" / "12,15" (rows silently emptied, selections cleared or rejected with 422, maps stored as text) and an unchecked Boolean arrived as "false", which PHP casts to true.

Structured values and Eloquent casts

MultiSelect, KeyValue and the multiple-file modes of File / Image persist a list or a map. Their fill() looks at the model before deciding who serialises it:

• Uncast column (a plain string / text / json column with no entry in $casts): the field writes a single JSON-encoded string, exactly as before.
• JSON-family cast ('array', 'json', 'object', 'collection' and their 'encrypted:…' variants) or class cast (AsArrayObject::class, AsCollection::class, AsEnumCollection::of(...), any Castable): the field hands the cast the PHP array and the cast serialises it once. Reading the attribute back through the cast yields an array (or the cast's object), never a JSON string.
• Scalar cast ('string', 'integer', …): treated like an uncast column; the field encodes.

So both of these store ["available","reserved"] once and read back as an array:

// Model
protected $casts = ['publish_states' => 'array'];
 
// Resource
MultiSelect::make('publish_states')->options([...]);

// Model: no cast on `publish_states`
// Resource
MultiSelect::make('publish_states')->options([...]);  // $model->publish_states is the JSON string; resolve() decodes it for the form

Before v1.37.3 a cast attribute was double-encoded (a JSON string of a JSON string) on the first save through the admin form, and every later read through the cast returned a string.

Fluent Configuration

Visibility

Granular Visibility

Convenience Visibility Presets

Context-Aware Visibility

Resolution rules per context:

Field authorization: canSee() and canSeeForModel()

A field the user cannot see is hidden by the server, not only by the UI. canSee() hides it for the request, canSeeForModel() for one record, and both hold on every endpoint:

• Reads. canSee() leaves the field out of every field list of the schema and of every value the API sends. canSeeForModel() leaves its value out of each record it hides the field for: the index, the detail, the values of the update form, the replicate form, the rows and the record of a relationship panel (and the responses of its inline create and update), the rows of a lens, the peek card, and for a pivot field the _pivot values of the attached records. The schema describes the resource, not a record, so each record lists under _hidden the attributes of the fields it hides (v1.38.0), and the pages leave those fields out instead of rendering them empty: the detail page, the detail and quick-look drawers, the update page and drawer (which neither render nor send them), the card of a HasOne / MorphOne, and the rows of the index, a lens and a relationship panel, where the field's cell stays empty for that record. A layout container left without fields is left out too. The _pivot values of an attached record list the pivot fields hidden for its pivot row the same way, and the panel leaves them out of the row and of its pivot edit form. The create forms leave out a field hidden for the new model (see Creates below).
• Writes. A hidden field is neither validated nor written, like a readonly() field: the request is accepted, the other fields are written and the column keeps its value. This holds on every endpoint that writes a record through its fields: the resource create and update, the inline create, the inline create and update of a HasMany / HasOne / MorphMany / MorphOne panel, and the attach and pivot update of a BelongsToMany / MorphToMany for its pivot fields (the attach stores the field's default()).
• Creates. canSeeForModel() is decided on the record written before any value of the request is written to it: the stored record on an update and, on a create, the new, unsaved model, as Nova resolves the fields of a create on a fresh model. A callback that grants on the record's stored values (an owner column, exists, a policy that reads them) denies on a create, and the create does not write the field. The create forms leave such a field out (v1.38.0): the schema's fieldsForCreate (a layout container left without fields goes with them) and fieldsForInlineCreate, and the inline-create schema, are decided on a new model. Grant on ! $model->exists to let a create write it:

Currency::make('salary')
    ->canSeeForModel(fn (Request $request, Employee $employee): bool => ! $employee->exists
        || ($request->user()?->can('viewSalary', $employee) ?? false));

• Pivot fields. The model a pivot field's canSeeForModel() receives is the pivot row, an instance of the relationship's pivot class (the ->using() class, else Pivot / MorphPivot) whose pivotParent is the parent record: the attached row when the pivot values are read or updated and when the pivot edit modal asks for a picker's options, a new row on attach and in the attach modal. The list of records to attach names the pivot fields a new row hides (meta.hiddenPivotFields), and the attach modal leaves them out (v1.38.0+; before, it offered an input the attach then ignored, storing the field's default()).
• Relationship fields. A HasMany, HasOne, MorphMany, MorphOne, BelongsToMany or MorphToMany field that canSeeForModel() hides for the parent record answers 404 on every endpoint of its panel (the list, its create, update and delete, the attach, the detach, the pivot update, the pivot actions and the pickers of its pivot fields), as a relationship the resource does not declare.
• Per-field endpoints. The options of a relation picker (on a form, among an Action's or a pivot action's fields, among pivot fields), the option search of a Select (of a resource or a Tool), the Slug check and the dependsOn sync answer for a hidden field exactly as for an attribute nothing declares: 404 for a picker and the Slug check, 422 for the Select search and the sync. So does a field of a Repeater row the user cannot see, and every row field of a Repeater the user cannot see. On a form, canSeeForModel() is decided on the record the update form edits, or on the new model of a create form.
• Action fields. An Action field the user cannot see is left out of the modal, is not validated and never takes its value from the request. See Actions → Fields the request cannot set.
• Sorting. A list is sorted only by a sortable() field the user can see (v1.38.0): the order of the rows would otherwise tell the order of the field's values. A ?sort= naming a field canSee() hides is ignored like one naming an unknown attribute (the other keys of a multi-key ?sort= still apply), and the list keeps its default order. This holds on every list that takes ?sort=: the resource index (its defaultSort() too), the rows of a HasMany, MorphMany, BelongsToMany and MorphToMany panel, and a lens, which is sorted by its own sortable fields only (see Lenses → Which columns sort a lens).
• Searching. A search matches its term only on the searchable() fields the user can see (v1.38.0): the rows a term returns would otherwise tell which records hold it in a field the user may not read. This holds on every search built from the fields' searchable() flags: the resource index, the rows of a relationship panel and its attach picker, the global search (see Global Search → Fields the user cannot see) and a relation picker (BelongsTo, MorphTo, Tag), which searches the title it shows when none of the related resource's searchable fields is left. A field:value token naming a field the user cannot see is dropped like one naming an unknown field. What a resource declares itself is searched as declared: its searchableRelations() paths, its searchQuery() predicate and, with Scout, its toSearchableArray().
• Layouts. The rules are the same whatever layout container holds the field: Panel, Section, or directly a Tab.

A field inside a Repeater row follows canSee() (see Repeater → Readonly, computed, hidden and immutable row fields); canSeeForModel() is not applied to row fields.

canSeeForModel() is decided on one record, so it cannot be decided for a list or a search, which span many: a sortable() field it hides on some records still orders the lists that show them, and a searchable() one is still searched, so the order of the rows and the rows a term returns tell something about the values of the records it is hidden on. When they must stay hidden, do not make the field sortable() / searchable(), or hide it with canSee() from the users who may not see it on every record.

Before v1.38.0 canSeeForModel() only hid the value on the resource's own reads (the index, the detail, the update form values, the replicate form). The resource create and update, the inline create and the inline forms of a relationship panel validated a field it hides and wrote the value the request sent (and the update form, which sends every field it lists, emptied the column); the relationship panels, the lens rows and the peek card sent its value; a relationship field it hides still served its panel; and a pivot field's callback was never asked. The per-field endpoints found a field whatever canSee() said, and an Action field hidden with canSee() was listed in the modal, validated and handed to handle(). A ?sort= naming a sortable field the user cannot see ordered the resource index, the relationship panels and a lens by that field, and a lens was sorted by any column ?sort= named. Every search matched the searchable fields the user cannot see too, and a field:value token could name one. The create forms listed a field canSeeForModel() hides for the new model, and the pages rendered a field a record hides empty (a hidden Boolean read "No"), since nothing told it from an empty one. A field placed directly in a Tab ignored canSee() altogether: the schema listed it, the record's values carried it, and the create and the update validated it and wrote the value the request sent.

Sortable / Searchable

Sorting by a computed key (sortUsing())

A key that is not a column of the listed table (a category's position, kept in another table) cannot be ordered by orderBy($attribute). sortUsing() hands the ordering to a closure, which receives the query and the requested SortDirection:

BelongsTo::make('Category', 'category')
    ->sortUsing(fn (Builder $query, SortDirection $direction) => $query->orderBy(
        Category::select('position')->whereColumn('categories.id', 'promotion_materials.category_id'),
        $direction->value,
    )),

• It implies sortable().
• It applies on every surface that sorts by the attribute: the index, a lens and the relationship panels, so a panel and the index agree, and in a multi-key ?sort= and in defaultSort().
• The closure only adds order clauses; it must not add where clauses (documented, not enforced).
• A field the user cannot see (canSee()) is not sortable through it either: the closure never runs.

Validation

Context-aware example — password is required on create but optional on update (the canonical pattern):

Password::make('password')
    ->rules(['min:8'])              // applies on every context
    ->creationRules(['required'])   // create only
    ->updateRules(['nullable']);    // update only

Every endpoint that writes through fields calls buildRules('create') on create and buildRules('update') on update: the resource's own POST and PUT, the inline create and update of the HasMany / HasOne / MorphMany / MorphOne panels, and the attach and pivot update of BelongsToMany / MorphToMany pivot fields. The schema endpoint also exposes both rule sets under creationRules / updateRules keys so the React frontend can pre-validate per context.

When creationRules contains required, the base sometimes rule is automatically stripped — sometimes short-circuits validation when a key is missing and would defeat the required directive otherwise.

Conditional required rules (v2.10.0)

A field whose rules carry a conditional sibling of required (required_if:type,company, required_unless, required_with, required_without, required_if_accepted, required_array_keys, ...) is required only when Laravel's condition holds:

Select::make('type')->options(['person' => 'Person', 'company' => 'Company'])->rules(['required']),
Text::make('first_name')->rules(['nullable', 'string', 'required_if:type,person']),
Text::make('legal_name')->rules(['nullable', 'string', 'required_if:type,company']),

A person payload without legal_name is valid, and one without first_name fails with a 422 on first_name. Martis compares as Nova does (in_array('required', $rules)): only the exact required string, or a rule object that renders as exactly required (Rule::requiredIf(true)), flags the field as required, adds the asterisk and puts a literal required in front of the rules. Before v2.10.0 any rule that started with required did, so two mutually exclusive required_if fields made every create fail. Because sometimes skips every rule for a key the request leaves out, the base rules also leave it out when a conditional required rule is present, or required_if could never refuse a missing key.

A conditional field shows no asterisk. To show one, call ->required() (always required), or declare Rule::requiredIf(true) or 'required' when it is. On update the rules behave as below: a key the request does not send runs none of them.

What an update validates

On update a field is validated only when the request sends it. The controller drops the literal required string from the field's rules and puts sometimes first, so a payload that carries some fields leaves the others alone. Every other rule is kept, whatever its type: strings such as required_with:…, Rule:: builder objects (Rule::unique(...)->ignore(...), Rule::in(), Rule::enum(), Rule::requiredIf()), ValidationRule instances and closures. A key the request sends runs all of them (an implicit rule such as Rule::requiredIf() rejects a sent empty value); a key it does not send runs none.

Text::make('code')
    ->required()   // dropped on update: an update may omit `code`
    ->rules([
        // `$this->model` is the record being edited (unsaved, or null, on create).
        Rule::unique('invoices', 'code')->ignore($this->model?->getKey()),
        function (string $attribute, mixed $value, Closure $fail): void {
            if (str_contains((string) $value, ' ')) {
                $fail('The :attribute may not contain spaces.');
            }
        },
    ]);

This holds on every update endpoint: the resource's own PUT, the inline update of a HasMany / HasOne / MorphMany / MorphOne, and the pivot update of a BelongsToMany / MorphToMany. A record edited from its parent's detail page is validated exactly like the same record edited on its own page. Take the record to ignore from $this->model, not from the route: on the relationship endpoints the {id} route parameter is the parent's id. On a pivot update $this->model is the parent record; the pivot row is the route's {relatedId}.

Up to v1.37.3 the relationship endpoints validated less. The pivot update kept string rules only (every rule object and closure was skipped); the inline updates skipped closures and Rule::enum() / Rule::requiredIf() objects and answered any update of a related resource that declares a ValidationRule instance with a 500; and no relationship endpoint applied creationRules() / updateRules().

Immutable fields

immutable() flags a field as writable on create, readonly on update. On update the field is skipped silently: the request is accepted, the other fields are written and the column keeps its stored value. This holds on every endpoint that updates a record through its resource's fields (the resource's own PUT and the inline update of a HasMany / HasOne / MorphMany / MorphOne from the parent's detail page) and on the pivot update of a BelongsToMany / MorphToMany for its pivot fields. The resource's own POST, the inline creates and the attach write the value. A value the update sends still runs the field's rules, like any other field (see What an update validates).

Text::make('slug')->immutable()->required();

Common cases: slugs, account numbers, document references.

The forms follow the same split. The update forms render an immutable field read-only, exactly as they render a readonly() field, and still submit its stored value: the update page (also when a relation panel opens the record to edit it), the update drawer (DrawerOverride::update()) and the form that edits a pivot row. The create page, the create drawer, the inline create and the attach keep the input editable. The schema serialises the flag as immutable; a form built with useMartisForm({ context: 'update' }) (see Tool fields) resolves it the same way, and a custom input registered for the field type receives the field with readonly: true. A field inside a Repeater row is immutable row by row (v1.38.0+): a new row writes and validates the value it sends, a row the record stores keeps its value, on every storage mode, and an update form renders the field read-only on the stored rows only; an immutable Repeater as a whole is skipped on update like any field. See Repeater → Readonly, computed, hidden and immutable row fields. Up to v1.37.3 every form rendered an immutable field as an editable input, and the update dropped the new value silently.

Every bundled input renders a readonly field read-only, so the lock holds whatever the field type. The inputs with more than one control lock each of them: Avatar shows the stored image with the picker disabled and no Choose file / Remove buttons; BooleanGroup disables every checkbox; Repeater shows its rows (the collapse toggles still work) with read-only row fields and no control that adds, removes, duplicates, reorders or pastes rows; File / Image keep their download links and previews, drop the remove and Change buttons, disable the picker and ignore a dropped file; Audio keeps its player, drops the Replace and Remove buttons, disables the picker and ignores a dropped file; BelongsTo and MorphTo disable their pickers and offer no inline-create "+" (showCreateRelationButton()), and a record the modal creates after the field turned readonly leaves the value alone (v1.38.0+). A file dropped on a readonly File, Image or Audio input is still cancelled, so the browser does not open it in place of the form. Up to v1.37.3 Avatar, BooleanGroup, Repeater, File and Image ignored readonly() (File / Image only disabled their hidden file input), so a readonly field of those types took a change in the form that the save then dropped (200, column unchanged), and a file dropped on a readonly Audio field was not cancelled: the browser opened it in the tab and left the form. Before v1.38.0 the "+" of a readonly BelongsTo / MorphTo stayed live: it created a real record and selected it, the update dropped the new value and left a record nothing points to, and on a nested create it replaced the locked parent on screen while the record was still created under the parent in the URL.

The pivot endpoints write each pivot field (in the fields() of a BelongsToMany / MorphToMany) through its fill(), and readonly() holds there too: a readonly pivot field never takes its value from the request. The attach stores its default() instead, as it does for any pivot field the request omits, and the pivot update leaves the column alone. See Relationships → With Pivot Fields.

Up to v1.37.3 only the resource's own update skipped an immutable field: the inline update of a HasMany / HasOne / MorphMany / MorphOne and the pivot update wrote it like any other field, and the attach and the pivot update also wrote a readonly pivot field from the request.

Sensitive fields

sensitive() marks the value a field carries as a secret (v2.4.0+): an API key, a token or a one-time code that an Action collects in its modal under a plain Text field. The action event log keeps ****** (ActionEventRedactor::MASK) in place of the value, in the event of a run, a failed run, a queued run and a pivot action. Password and PasswordConfirmation are sensitive without the call (Password::make('x')->sensitive(false) turns it off); isSensitive() reads the flag.

Text::make('api_key')->sensitive();

The flag changes nothing else: the action receives the value, the field is validated and rendered as before.

Reactive fields — dependsOn(['field'], Closure)

⭐ Martis differential — declare that a field reacts to one or more sibling fields. The frontend watches the listed attributes and, every time the user edits any of them, posts the live form payload to POST /api/resources/{r}/sync-field. The backend re-runs the closure with the fresh data and returns the updated field descriptor (visibility, readonly, required, options, placeholder, help, default, meta, …) — the live form replaces its local descriptor with the response.

The closure receives:

• array<string, mixed> $formData — the live form values, keyed by field attribute (the watched siblings are guaranteed; any other touched attribute is forwarded too).
• Illuminate\Http\Request $request — the active request (auth user, locale, headers).
• static $field — the field instance, mutable. Call any of the regular fluent methods on it.

Examples:

// Make `price` required only when `is_paid` is true:
Number::make('price')
    ->dependsOn(['is_paid'], function (array $form, Request $r, Number $field) {
        $field->required((bool) ($form['is_paid'] ?? false));
    });
 
// Reload Select options whenever `category_id` changes:
Select::make('subcategory_id')
    ->dependsOn(['category_id'], function (array $form, Request $r, Select $field) {
        $field->options(
            \App\Models\Subcategory::query()
                ->where('category_id', $form['category_id'] ?? null)
                ->pluck('name', 'id')
                ->all(),
        );
    });
 
// Branch on the current user — works in both create and update contexts:
Text::make('access_code')
    ->dependsOn(['plan'], function (array $form, Request $r, Text $field) {
        if (($form['plan'] ?? null) === 'enterprise' && $r->user()?->isAdmin()) {
            $field->readonly(false);
        } else {
            $field->readonly(true);
        }
    });

Show, hide and relabel a field from a sibling (v2.17.0)

Call hide() and show() on the field, as Nova's dependent fields do. A field that starts hidden calls hide() where it is defined; the callback shows it when the sibling asks for it. The callback also runs when the form opens, so an update form shows or hides the field from the record's current values before anything is edited. withLabel() in the callback changes the label the same way.

Select::make('language')->options(['pt' => 'Portuguese', 'en' => 'English', 'both' => 'Both languages']),
 
Text::make('title')
    ->dependsOn(['language'], function (array $form, Request $r, Text $field) {
        $field->withLabel(($form['language'] ?? null) === 'both' ? 'Title (PT)' : 'Title');
    }),
 
Text::make('title_en')
    ->hide()
    ->rules(['nullable', 'required_if:language,both'])
    ->dependsOn(['language'], function (array $form, Request $r, Text $field) {
        ($form['language'] ?? null) === 'both' ? $field->show()->withLabel('Title (EN)') : $field->hide();
    }),

• A hidden field is not drawn, and its value is left out of the submit (not sent empty), so an update keeps the stored value. A panel, section or tab whose fields are all hidden is not drawn either.
• The server validates with the field's own rules, not with the callback: a field that can be hidden must not be plain required. Use a conditional rule (required_if:language,both above), which the hidden case (no value sent) satisfies.
• hide() differs from hideFromForms(): hideFromForms() takes the field off the form schema for good, hide() keeps it there so show() can bring it back.

Wire format. The schema endpoint serializes dependsOn: { fields: ['attr1', 'attr2'] } (an object) for reactive fields and null for non-reactive ones. The frontend useDependsOnSync hook subscribes to the listed attributes, debounces 200ms, and POSTs the payload when any watched value changes — older requests are aborted via AbortController so the latest value always wins.

Endpoint. POST /api/resources/{r}/sync-field body: { field: string, formData: object, context?: 'create' | 'update' }. Response: a single field descriptor in the same shape as schema.fields[]. Authorization gates the same as create/update. The field is looked up on the form of context only, layout containers included: fieldsForUpdate() for update, fieldsForCreate() then the inline-create modal's fieldsForInlineCreate() for create (v1.38.0: a reactive field declared on the inline-create form alone used to answer 422). A field that is not on that form is 422 Unknown field.

Closure-aware setters

Most field setters accept either a static value or a closure that resolves at request time. Reach for the closure form whenever the result depends on the authenticated user, the locale, the active tenant, or anything else that lives on the Request.

The closure receives the active Request (or null when called outside an HTTP context, e.g. a queue worker) and must return the resolved value. Static values still work — the closure form is purely additive.

Examples:

// Per-user defaults
Text::make('owner_id')
    ->default(fn ($request) => $request?->user()?->id);
 
// A default read from the create link (`/resources/versions/create?of=12`).
// The resource lists the key in `acceptsPrefill()`; see
// resources.md#prefill-the-create-form-from-a-link--acceptsprefill
BelongsTo::make('document', 'Document')
    ->default(fn (?Request $request) => $request?->query('of'));
 
// Keep the category for the next record on "Create & add another"
Select::make('category')->options($categories)->sticky();
 
// Conditional readonly based on policy
Text::make('email')
    ->readonly(fn ($request) => $request?->user()?->cannot('change-email'));
 
// Required only for non-admins
Text::make('reason')
    ->required(fn ($request) => $request?->user()?->cannot('skip-reason'));
 
// Locale-aware label and placeholder
Text::make('greeting')
    ->withLabel(fn () => __('fields.greeting.label'))
    ->placeholder(fn () => __('fields.greeting.placeholder'));
 
// Help text that reads live state from the user. help() is HTML: escape
// anything that is not yours with e() (the panel sanitises it too).
Text::make('quota')
    ->help(fn ($request) => 'Quota left: '.e($request?->user()?->quota()));
 
// Options pulled from the database: Select / MultiSelect / BooleanGroup.
// All three read [value => label], as in Nova, so pluck('name', 'id') stores the id.
Select::make('owner_id')
    ->options(fn () => User::query()->pluck('name', 'id')->all());
 
MultiSelect::make('skills')
    ->options(fn () => [
        'php'   => ['label' => 'PHP', 'group' => 'Backend'],
        'go'    => ['label' => 'Go', 'group' => 'Backend'],
        'react' => ['label' => 'React', 'group' => 'Frontend'],
    ]);
 
// BooleanGroup reads [flag key => label]: availablePermissions() returns that map.
BooleanGroup::make('permissions')
    ->options(fn ($request) => $request?->user()?->availablePermissions()->all() ?? []);
 
// Validation rules that vary per role
Text::make('cap')
    ->rules(fn ($request) => $request?->user()?->isAdmin()
        ? ['nullable']
        : ['required', 'integer', 'max:100']);

withLabel() vs the constructor label

Field::make('attribute', 'Label') accepts the label as a positional argument. withLabel() is the post-construction setter that also accepts a closure. The contract method label() is the getter — withLabel() is named explicitly to avoid overloading it.

rules(callable) semantics

Static and closure rule definitions do not compose. The last call wins:

Text::make('field')
    ->rules(['min:1'])      // pinned
    ->rules(fn () => ['email']); // closure replaces ['min:1']
 
Text::make('field')
    ->rules(fn () => ['email']) // closure
    ->rules(['min:1']);         // static replaces the closure

If you need both static and dynamic rules, return them together from a single closure:

->rules(fn ($request) => array_merge(['min:1'], $request?->user()?->isAdmin() ? [] : ['max:100']))

Unique Validation

Email::make('email')
    ->unique(['users', 'email'], 'This email is already in use.')

When the database index refuses the write (v2.9.0)

The rule runs before the write, so a unique index can still refuse it: two saves racing past the rule, or an index the rule does not mirror (a case-insensitive lower(email) index, a composite index). Martis answers that write with a 422, as the rule would, on every endpoint that saves a record: create, update, inline create, and a relationship panel's create, update, attach and pivot update. The error sits on each field of the form whose column the index covers, with the field's unique() message, or else Laravel's validation.unique line on its label ("The Email has already been taken."). The response's message is A record with this value already exists. Please use a unique value.

The columns come from the database's error message:

An index name works when it contains the column, as Laravel's default {table}_{column}_unique does (users_email_lower_unique works too). It is split on every column of the table, so users_first_name_unique names first_name, never a written name. A name that contains none of the form's columns (uniq_domain), or an index on a column the form does not write, answers the same 422 without a field error, so the form shows the message only. Only the fields of the form are matched, so a function name (lower) or a column the form lacks never becomes an error key. A foreign key or NOT NULL failure answers a 500 with a message of its own. No answer ever carries SQL or the database's message.

Customization Hooks

The core hooks let you replace the default read / write / format behaviour of a field with arbitrary logic. Unlike the lazy setters in Closure-aware setters, these hooks do not have a static counterpart — they ARE the customization.

⭐ Martis differential 1 — ?Request is forwarded to every hook

The active Request (or null when there is no HTTP context, e.g. a queue worker) is forwarded as the fourth argument of every hook. Closures with three parameters keep working unchanged because PHP silently drops trailing arguments that the callback did not declare.

// Per-tenant resolve without calling request() manually:
Text::make('balance')->resolveUsing(
    fn ($value, $model, $attribute, ?Request $request) =>
        $request?->user()?->isAdmin()
            ? number_format((float) $value, 2)
            : '*****',
);
 
// Per-locale fill that auto-converts decimals:
Number::make('price')->fillUsing(
    fn (Model $model, $value, string $attribute, ?Request $request) =>
        $model->setAttribute(
            $attribute,
            (float) str_replace(
                $request?->getPreferredLanguage(['pt_BR', 'en']) === 'pt_BR' ? ',' : '.',
                '.',
                (string) $value,
            ),
        ),
);

⭐ Martis differential 2 — displayUsing() accepts a chainable pipeline

displayUsing() accepts either a single callable (legacy) or a list<callable>. When an array is passed, each callback receives the output of the previous one — equivalent in spirit to array_reduce.

// Pipeline: cast → format → prefix
Text::make('amount')->displayUsing([
    fn ($v) => (float) $v,
    fn ($v) => number_format($v, 2),
    fn ($v) => "R$ {$v}",
]);
 
// Pipeline + per-stage Request access:
Text::make('balance')->displayUsing([
    fn ($v) => (float) $v,
    fn ($v, $m, $attr, ?Request $r) => $r?->user()?->isAdmin()
        ? number_format($v, 2)
        : '*****',
    fn ($v) => "<strong>{$v}</strong>",
]);

If any entry in the array is not callable, displayUsing() throws InvalidArgumentException immediately at definition time — you get the failure when the resource boots, not deep inside a request.

A subsequent single-callable call replaces the entire pipeline. A subsequent array call replaces the prior single callable. The hook is monotonic: only the most recent definition is active.

Backward compatibility

The 4th ?Request $request argument is purely additive. Existing 3-arg callbacks keep their semantics unchanged.

Computed fields

Every field has an attribute name, and by default resolve() reads that name from the model before anything else runs. That read is Eloquent's getAttribute(), which has two traps a resolveUsing() callback cannot avoid, because the read happens first:

• A name that matches a model method (mode, status, type, …) is treated as a relationship: getAttribute('mode') calls mode() and throws LogicException: …::mode must return a relationship instance when the method returns anything else (an enum, a string, a DTO). On the resource index that surfaces as an HTTP 500.
• A name with no backing column raises MissingAttributeException on persisted models once the host enables Model::shouldBeStrict().

computed() opts the field out of that read. The attribute name becomes a pure payload key (it still has to be unique within the resource) and the value comes from a callback:

// Value source: model-first callback (recommended)
Badge::make('mode', 'Mode')
    ->computed(fn (Channel $channel): string => $channel->mode()->value)
    ->map(['push' => 'info', 'feed' => 'success']);
 
// Flag only: the existing resolveUsing() receives null as $value
Badge::make('mode', 'Mode')
    ->computed()
    ->resolveUsing(fn ($value, Channel $channel) => $channel->mode()->value);

Callback signature: fn (Model $model, string $attribute, ?Request $request): mixed. As with the other hooks, trailing arguments are optional: fn (Channel $channel) => … works.

The computed value enters the normal pipeline, computed → resolveUsing → displayUsing, so formatting and per-request logic work exactly as for stored fields. Without a callback the raw value is null: resolveUsing() receives null, and with no resolveUsing() either the field resolves to null. A later computed() call replaces the callback.

What computed() changes besides the read:

Which fields honour computed(): every field whose value resolution goes through Field::resolve() (Text, Badge, Status, Number, Boolean, Date, Select, …) plus the ones with their own resolve() that read through the shared seam: KeyValue, MultiSelect, Sparkline, File, Image, Gravatar. Relationship fields read a foreign key or relation rather than the attribute, Icon has its own display/stored/computed modes, UiAvatar derives its initials from from() / the attribute directly, and Repeater has its own storage modes; computed() does not apply to them.

Custom field types that override resolve() must read the model through $this->resolveAttribute($model, $attribute) instead of $model->getAttribute(), otherwise computed() is silently ineffective for that type. A type that only needs to look at the stored value (for example to check it) should override inspectResolvedValue(Model $model, string $attribute, mixed $value): void instead: Field::resolve() calls it with the value it just read, before resolveUsing(), so the model is read once and an accessor or a computed() callback does not run twice per row.

Without computed(), the rule stands: a field's attribute must be a real attribute (column, cast, accessor or loaded relation) and must not share its name with a model method.

Component Override

Metadata

Index Table Column Width

Controls how the field renders as a column in the index table. See resources.md for the Resource-level tableLayout() switch.

textAlign and hideBelow apply to the resource index and lenses. The relationship tables on a detail page do not read the column metadata.

Type defaults (applied automatically unless overridden):

All defaults can be disabled globally via config('martis.index.column_defaults', false) (env MARTIS_INDEX_COLUMN_DEFAULTS). Explicit per-field calls still apply. See resources.md for details.

Serialization

Tooltips (Martis differential)

⭐ Martis-exclusive. In addition to help() (plain text under the input), Martis adds label tooltips as a separate channel so authors can surface contextual guidance without committing valuable real estate to permanent inline text.

Why it matters

• help() is always visible. It costs vertical space on every form render, for every user, regardless of how long they've been using the resource.
• A tooltip is opt-in: the hint shows only when the user hovers the discreet (?) icon next to the label. Experienced users never see it; new users have it one hover away.
• HTML support means you can pack rich, multi-line guidance (lists, bold, line breaks) into a single call without bloating the form.

API

Text::make('name', 'Full name')
    ->tooltip('<strong>Full legal name</strong>.<br />Examples:<br />• John Smith<br />• Ana Pereira<br /><br /><em>Avoid abbreviations.</em>');

The tooltip string ships to the frontend in the serialized field under the key tooltip and is rendered by the global MartisTooltip component behind the (?) label icon on any form renderer (Panel, Section, TabGroup, ResourceCreate, ResourceUpdate) and on detail labels rendered inside Sections/TabGroups.

HTML support

The label renderer registers its (?) icon as a trigger that may show HTML (htmlTooltip(), see Tooltip Standard), which makes the global MartisTooltip provider render the text as HTML; any other data-pr-tooltip trigger keeps the default plain-text escape, whatever attributes it carries (the metric help() tooltip and an extension's own triggers register the same way). Allowed markup: any inline HTML (<br />, <strong>, <em>, <ul>/<li>, <code>, <a>). The markup is sanitised before it is shown (scripts, event handlers, unsafe URLs, data-* attributes, the style attribute and element, id, name, forms and form controls are removed), but the author is still responsible for producing it and never puts user or record data in it; prefer localised strings from __() / i18n dictionaries to keep content reviewable.

When to use tooltip() vs help()

Both can coexist on the same field: ->help('Must be unique')->tooltip('<strong>Uniqueness rules</strong><br />...').

Frontend behaviour

• The (?) icon uses the muted text colour so it reads as a quiet affordance.
• Hover delay is 500 ms — long enough that a cursor skimming the form doesn't flash tooltips, short enough that intentional hover feels responsive.
• Both channels wrap. The bubble is shrink-to-fit up to 360 px (never wider than the viewport minus 16 px): a short label stays on one line, a sentence wraps inside the bubble, and a long unbroken token (a URL, an id) breaks inside it (overflow-wrap: anywhere) instead of running past its edge. Plain text renders at 11 px with a tight padding; HTML content at 12 px with a 220 px minimum width so paragraphs read as prose. Since v1.38.0; before, a plain tooltip was pinned to one line in a 300 px box and a long one spilled out of the bubble.
• Plain text stays plain whatever its length: a sentence in data-pr-tooltip wraps without the HTML opt-in, and markup in it renders literally. Use htmlTooltip() only for content that needs markup.
• Position respects the trigger's data-pr-position (defaults to top). The bubble is measured first, flips to the opposite side when the requested one has no room for it (a left / right bubble with room on neither side goes above or below), and is kept inside the viewport with an 8 px margin; the arrow moves along the edge so it keeps pointing at the trigger. While it is open the bubble follows its trigger when the page or a container scrolls, and closes once the trigger leaves the viewport (v1.38.0+).

Why NOT a Tooltip field class

We deliberately rejected adding a Tooltip::make() field. Reasons:

1. A Field represents a column or value. A pure tooltip has nothing to read, write, validate, or serialise — it breaks the contract.
2. Tooltips are a presentation concern that applies to fields, not a field type of their own. Inverting that relationship forces authors to position an empty "tooltip field" inside the form, competing with real fields for colSpan and layout placement.
3. The ->tooltip() modifier is universal: it applies to every existing and future field without touching the UI layer.

If you need a hint unrelated to any single field (e.g. a section intro), use Panel::make('', [])->description(...) or Section::make(...)->description(...) — not a field.

Field Types

Id

Type identifier: id Extends: Field File: src/Fields/Id.php

Auto-incrementing primary key. Read-only, hidden from forms, sortable by default.

Id::make()           // defaults: attribute='id', label='ID'
Id::make('uuid')     // custom attribute

Default overrides:

• readonly = true
• showOnForms = false
• sortable = true

Specific methods: None (all from base).

Text

Type identifier: text Extends: Field File: src/Fields/Text.php

Single-line text input. Renders as <input type="text">.

Text::make('title')
    ->sortable()
    ->searchable()
    ->required()
    ->placeholder('Enter title...')

Specific methods: None (all from base).

Textarea

Type identifier: textarea Extends: Field File: src/Fields/Textarea.php

Multi-line text area. Renders as <textarea>. It opens at its row count and grows to fit a longer text, and the form or the modal body scrolls.

Textarea::make('body', 'Content')
    ->rows(10)
    ->nullable()
    ->hideFromIndex()

Extra attributes: rows

Number

Type identifier: number Extends: Field File: src/Fields/Number.php

Numeric input. Renders as <input type="number">.

Number::make('price', 'Price')
    ->min(0)
    ->max(9999)
    ->step(0.01)
    ->integer()
    ->nullable()

Extra attributes: min, max, step (only non-null values)

Input: the form input takes the decimal separator of the user's Martis locale (v2.1.0). The index and detail pages show the value as stored.

Boolean

Type identifier: boolean Extends: Field File: src/Fields/Boolean.php

Toggle/checkbox field. Casts values to strict boolean.

Boolean::make('is_active', 'Active')
    ->trueLabel('Enabled')
    ->falseLabel('Disabled')
    ->sortable()

Overrides: resolve() casts to (bool), fill() casts incoming to (bool). Extra attributes: trueLabel, falseLabel

BooleanGroup

Type identifier: boolean_group Extends: Field File: src/Fields/BooleanGroup.php

Map of named boolean flags stored as JSON. Ideal for permission grids, feature gates, notification preferences.

BooleanGroup::make('permissions')
    ->options([
        'clients.view' => 'View clients',
        'clients.edit' => 'Edit clients',
        'billing.view' => 'View billing',
    ])
    ->grouped([
        'Clients' => ['clients.view', 'clients.edit'],
        'Billing' => ['billing.view'],
    ])
    ->requireAny();

The server enforces the limits on the set fill() stores (v2.4.0): the submitted keys the field offers, each read as a boolean the way fill() reads it (true, 1, '1', 'true', 'on', 'yes' are on, in any letter case), so a key the options do not name never counts toward either limit and a truthy spelling never escapes maxChecked().

⚠️ When options() is given a closure, requireAll() cannot pre-compute its target at field declaration time — the closure has not run yet. Pair the closure form with minChecked(int) directly, or use requireAny() (always 1).

Storage format: {"flag":true,"other":false} on a plain column, or the map itself through an array / json cast. Overrides: resolve() decodes a JSON string or array to the normalised {key: bool} map; fill() decodes a JSON string to the map (the multipart path, or a direct call) and writes only the flags options() offers (below).

What a write stores. The options a user is offered are the set of flags that user may change (an options() closure can scope them to the authenticated user), so fill() projects the submitted map onto them (since v2.4.0):

• a submitted key the options do not name is ignored, so a crafted request cannot store {"admin": true} next to the flags it was shown;
• each offered value becomes a boolean (true, 1, '1', 'true', 'on', 'yes' are on, everything else is off), and an offered flag the submission leaves out is off;
• a flag already stored that the user was not offered keeps its stored value, so an editor who sees a subset of the flags can neither switch on a flag they were not shown nor erase one an administrator set;
• an empty value (null, '') switches every offered flag off and stores null when no hidden flag is left to keep;
• a fillUsing() callback receives the offered flags only (the same projection), and a readonly or computed() field writes nothing, as for every field.

On a column without an array / json cast the map is stored as a JSON string, as for KeyValue and MultiSelect (see Structured values and Eloquent casts).

⭐ Martis differentials: grouped sections, min/max live counter, requireAny/All presets.

Avatar

Type identifier: avatar Extends: Image File: src/Fields/Avatar.php

Image upload specialised for profile pictures. Inherits every upload helper from Image (disk, storagePath, maxSize, thumbnail, …).

Zero configuration needed for the empty state — when a record has no upload AND the developer didn't declare an explicit fallback(), the field renders coloured initials inline on one of the theme's 16 avatar tokens: the same letters and colour as the Topbar and profile avatars of a user with that name. No external service call, no extra DB column, no boilerplate closure.

// One-liner: uploaded photo when present, coloured initials inline otherwise.
Avatar::make('avatar_path')
    ->disk('public')
    ->storagePath('team-avatars')
    ->maxSize(2048)
    ->circle()
    ->colorFrom('brand_color'); // optional: use a brand attribute instead of the hash palette

Resolution priority (per row):

Initials payload. When the field falls back to initials, its value carries isInitialsFallback: true and:

A custom component that reads the payload paints var(--martis-avatar-{palette}) when palette is set, so it follows the theme like the built-in circle, and color otherwise.

⭐ Martis differentials:

• Zero-config inline initials fallback — no external service, no extra closures, works out of the box.
• Deterministic 16-hue palette declared as --martis-avatar-1..16 tokens, stable across light/dark themes and redefinable by a theme. The server picks one from a hash of the seed (name, email, slug) — two users with the same name always get the same colour.
• Empty-seed glyph — when the record has no name/initials, the field renders a muted user icon inside .martis-avatar-fallback instead of a bare em-dash.
• Per-row Closure-aware fallback() when you do want a custom URL.
• Typed AvatarShape enum instead of a boolean rounded().
• Initials and palette shared with UiAvatar, the Topbar and the profile page through Martis\Support\Initials (the fields reach it via the ResolvesInitialsPayload trait).

UiAvatar

Type identifier: ui_avatar Extends: Field File: src/Fields/UiAvatar.php

Display-only initials pill. Differs from Avatar in one key way: it never takes an upload — the value is computed entirely from the model.

When to pick UiAvatar over Avatar:

UiAvatar::make('avatar_initials')
    ->from('name')
    ->colorFrom('brand_color')
    ->circle();

The value has the same initials, palette, color and seed keys as the Avatar initials payload, plus shape.

⭐ Martis differentials: deterministic 16-slot palette from seed hash (same name → same colour, zero DB; a theme recolours it through the --martis-avatar-N tokens), colorFrom('attribute') override, custom-initials closure, decoupled seed via from(). Computed with the record, painted inline: no external service call.

Audio

Type identifier: audio Extends: File File: src/Fields/Audio.php

File upload specialised for audio clips. Renders a fully custom on-brand player (accent play/pause button, waveform OR progress track, mono current/total timestamps, optional download affordance) and a drag-and-drop dropzone empty state. The native <audio controls> element is intentionally bypassed so the look stays consistent under both light and dark themes.

Audio::make('intro_audio_path')
    ->disk('public')
    ->storagePath('team-audio')
    ->maxSize(10240)
    ->downloadable(false);

Empty state. When no file is attached, the input renders a dashed dropzone with a Phosphor MusicNote icon, the audio_empty_title and audio_empty_hint copy, and a "Choose file" CTA. Drag-and-drop is supported.

i18n keys (in messages.php, all three locales):

audio_empty_title, audio_empty_hint, audio_browse, audio_replace, audio_remove, audio_play, audio_pause, audio_download.

⭐ Martis differentials: client-side canvas waveform via Web Audio API (no server rendering), custom player chrome that follows the design tokens, drag-and-drop dropzone, downloadable(bool) toggle.

Select

Type identifier: select Extends: Field File: src/Fields/Select.php

Version note. Martis v2.0 and later read options() as [value => label], Nova's order; Martis v1.x read [label => value]. On v1.x, flip the arrays in the examples below, or upgrade: see Upgrading.

Dropdown select with predefined options.

Select::make('status')
    ->options([
        'draft'     => 'Draft',
        'published' => 'Published',
        'archived'  => 'Archived',
    ])
    ->nullable()

Extra attributes: options, displayLabels, searchableOptions, allowCustomValues, remoteOptionsSearch

// Static options: [value => label]
Select::make('status')->options(['draft' => 'Draft', 'published' => 'Published']);
 
// Translated labels: the stored value stays fixed while the label is translated
Select::make('plan')->options([
    'free' => __('plans.free'),
    'pro'  => __('plans.pro'),
]);
 
// Database-backed options resolved at render time: stores the id
Select::make('owner_id')->options(fn () => User::query()->pluck('name', 'id')->all());
 
// Grouped options, in Nova's format
Select::make('size')->options([
    'MS' => ['label' => 'Small', 'group' => 'Men Sizes'],
    'WS' => ['label' => 'Small', 'group' => 'Women Sizes'],
]);
 
// Show the raw ISO code on the index column instead of the country name
Select::make('country_code')
    ->options(['PT' => 'Portugal', 'GB' => 'United Kingdom'])
    ->displayUsingValues();

Option order

options() reads [value => label], the order Nova uses for Select, MultiSelect and BooleanGroup: the key is what the field stores, the value is what the user sees. So pluck('name', 'id') stores the id, and two records with the same name stay two options. Before v2.0.0 Martis read the array label first; see Upgrading.

• A list is a map keyed 0, 1, 2…, so options(['Small', 'Large']) stores 0 and 1, as in Nova. When each value is its own label, pass array_combine($values, $values). A list of numbers is the trap: options([1, 2, 3]) stores 0, 1 and 2, so options(range(1, 12)) for months stores 0 for January.
• Grouped options map a value to ['label' => ..., 'group' => ...]. Any other array value throws an InvalidArgumentException that names the field and the option (the pre-v2 ['Group' => ['Label' => 'value']] format included). The Select dropdown shows each group under its heading, in the order the groups first appear, with ungrouped options on top; the MultiSelect list keeps groups and ungrouped options in the order they first appear.
• An enum class (options(Status::class), Martis extension) stores the case value of a backed enum, or the case name of a pure one, labelled with the headline of the case name.
• A Collection, or any other iterable or Arrayable, reads like an array, as in Nova: pass it straight in (options(User::query()->pluck('name', 'id'))) or return it from a closure (fn () => User::query()->pluck('name', 'id')), without ->all(). Passed straight in, the query runs when the field is built, on every request that builds it; from a closure, only when the options are read.
• searchOptionsUsing() returns the same shapes, in the same order, a Collection included. A non-empty list is keyed 0, 1, 2, so the field would store a position in that search's results, which changes with the term: it logs a warning, at most once per field per request.
• Filters are the exception, as in Nova: a filter's options(Request $request) returns [label => value]. See Filters.

Stored labels (Martis extension). Reading a record whose stored value matches the label of a static option and the value of none logs a warning, in production too, at most once per request for each model class and field: the options array is still written label first, or the record was saved while it was, and saving it again would store the wrong value. For options given as a list, a stored value that is the label of another option warns too (options([1, 2, 3]) holding a 1 saved under v1.x, which now shows as "2"). The check reads the stored value, before resolveUsing(). It skips options from a closure (so it never runs a query of its own), computed fields, and a Select with allowCustomValues(), where a typed label is a legitimate value. Both warnings assume the stored value is stale v1.x data, but a field can legitimately store a valid 0-based position that reads as another option's label, for example a Nova rating that stores 0..4 on purpose and shows "1".."5": call withoutOptionOrderWarnings() on the field (Martis extension) to silence both warnings for it once the array is confirmed right.

Validating against the options

A Select does not check, on the server, that the submitted value is one of its options. The dropdown only offers them, but a request can carry any value, and the field writes it as sent: a forged role_id, a status the list never showed, an option the picker hides from this user. Nova's Select behaves the same, so options() alone is a UI constraint, not a rule.

When the list must be closed, opt in:

Select::make('status')
    ->options(['draft' => 'Draft', 'live' => 'Live'])
    ->validateAgainstOptions();
 
// A closure of options: the query runs when a request is validated, not while the schema is built
Select::make('role_id')
    ->options(fn () => Role::query()->whereNull('provider_group_name')->pluck('name', 'id'))
    ->required()
    ->validateAgainstOptions();

• One rule, over getOptions(), with the options as they are when the request is validated. A value fails with martis::validation.not_in_options (The selected Status is invalid., translated in en, pt_PT and pt_BR, with the field's label) as a 422 on the field, before anything is written. It applies wherever the field's rules do: the resource's create and update, the inline creates, and the fields of an Action modal.
• By value, not by label, and only as a string or an integer: an option keyed 7 accepts 7 and '7', not '07', '7.0', 7.0, true or an array. Grouped options count by their value; a list (['Small', 'Large']) accepts 0 and 1; an enum class accepts its case values.
• An empty value is left to required() and nullable(), as for every other field. On create required() refuses it. On update every field's required is dropped (a form that leaves a field alone, a Password for one, sends it empty), so a request that names a required Select empty on update is not refused by it: the options rule has no value to judge, and the field is cleared. When an update must never clear it, add a rule object of your own that survives the drop: ->updateRules([Rule::requiredIf(true)]).
• Not for a list that is only a first page. A field with searchOptionsUsing() loads the rest of its options from the server, so a value the search returns is not in getOptions() and would be rejected: validate that field with a rule of your own. With allowCustomValues() the closed list wins and a typed value is rejected, so pick one of the two.
• A rule that depends on who asks (the roles this user may hand out) belongs in the options() closure, which receives the request: the same list then feeds the dropdown and the rule. The scaffolded InviteUser and BulkAssignRole actions do exactly that (see Invitations and Roles).

MultiSelect::validateAgainstOptions() is the same option for a selection: every selected value must be an option (one stray value fails the whole field), and anything that is not a list of strings and integers fails too.

Clear (X) icon. On a nullable() select, the clear icon appears only once a value is selected — an empty select has nothing to clear, so no X shows on the placeholder state.

Searchable options, custom values and server-side search (v1.37.0).

// Long list: search box over the options (matches label or value)
Select::make('currency')->options(Currency::all())->searchableOptions();
 
// Pick from the list or type a value the list does not carry
Select::make('model')->options(['gpt-4o' => 'gpt-4o'])->searchableOptions()->allowCustomValues();
 
// Very long list: keep the first page in options(), search the rest on the server
Select::make('model')
    ->options(fn () => ModelCatalog::top(50))
    // Both closures return [value => label]; a list would store positions.
    ->searchOptionsUsing(fn (string $term, ?Request $request) => ModelCatalog::search($term, limit: 50));

• searchableOptions() renders PrimeReact's filter box inside the panel; filtering happens in the browser over the serialised options. Coming from Nova: Nova's Select::searchable() is this method. In Martis, searchable() on any field (including Select) means "the column takes part in the resource search", and it is serialised as searchable; the option search box is a separate flag, searchableOptions.
• allowCustomValues() makes the control editable. A typed value reaches the form state on every keystroke, exactly like a Text field, and is stored as-is; SelectFieldDisplay renders a value with no matching option as the raw string. The field adds no Rule::in validation, so add one yourself when the list must be closed after all (validateAgainstOptions() is that rule, but it rejects a typed value, which defeats this flag: use one or the other).
• searchOptionsUsing() moves the search to the server. When the panel opens the frontend calls the field-options endpoint with an empty term (return your "first page" there), then again after each typing pause (300 ms), aborting the previous request; the initial options() list is shown until the first response lands. The endpoint is derived from the form's scope: GET /api/resources/{resource}/fields/{attribute}/options?context=create|update&id=<record> for a Resource form (gated on the create ability, or on the update ability with the edited record bound, like sync-field) and GET /api/tools/{uriKey}/fields/{attribute}/options for a Tool implementing ProvidesFields whose form passes toolKey (see Tool fields). A select in a Repeater row asks the same endpoints with the form's own context and names its row (&repeater={attribute}&repeatable={type}), where the server finds it (v1.38.0+; see Repeater → Relation pickers and remote selects in rows). Outside those two scopes (Action modals, a relationship's pivot fields, a frontend-only Tool form) the select falls back to local filtering over options(). The server decides what matches: results are shown as returned, never re-filtered in the browser. A stored value that is not in the current list is still shown in the control and can be cleared. An option picked from the results keeps its label in the control once the panel closes, a '' ("None") option included. Index and detail read labels from options() only, so a value that only the search returns shows raw there, and a '' shows the dash: list such an option in options() too when it must show its label. The term is trimmed and clamped to 255 characters before it reaches your closure. On a Resource form the select is looked up on the form of the context only: fieldsForUpdate(), or fieldsForCreate() and then the inline-create modal's fieldsForInlineCreate() (v1.38.0: a select declared on the inline-create form alone used to answer 422).

Filter variant + custom class (v1.29.0). When rendering a select through the runtime FieldInput (e.g. a filter bar inside a Tool), the frontend honours two extra keys on the field definition:

• variant: 'filter' — adds the compact martis-filter-dropdown class (the same look Martis's native resource filters use).
• className: '...' — forwarded verbatim onto the Dropdown root, so you can layer your own utility classes.
• searchableOptions: true / allowCustomValues: true / remoteOptionsSearch: true (v1.37.0) — the three Select flags above, usable from a frontend-only definition too. remoteOptionsSearch only does something when the form has a resourceKey or a toolKey.

// FieldDefinition passed to runtime.FieldInput
{ type: 'select', attribute: 'status', label: 'Status', variant: 'filter', className: 'w-48', options: [...] }

These are frontend-only rendering hints; they have no effect on a plain Select field inside a normal Resource form.

GuardSelect

Type identifier: select (inherits) Extends: Select File: src/Fields/GuardSelect.php

Dropdown of the auth guards configured in the host app's config/auth.php. Designed for guard_name columns on Spatie Permission / Role tables — most installs have a single guard (web), but the field gives the developer a confident UI to pick from instead of typing free text. Shipped in v1.8.0.

use Martis\Fields\GuardSelect;
use Martis\Fields\Slug;
 
public function fields(Request $request): array
{
    return [
        Id::make()->sortable(),
        Slug::make('name')
            ->separator('.')
            ->reserved(['*'])
            ->help(__('martis::permissions.name_help'))
            ->required(),
        GuardSelect::make('guard_name')
            ->help(__('martis::permissions.guard_help'))
            ->required(),
    ];
}

The label and value are always identical — guard names are tokens (web, api, sanctum) and translating them would be misleading. Server-side validation rejects any value not declared in config/auth.guards, which prevents Spatie Permission from later crashing on Role::users() (morphedByMany cannot resolve the User model for an unconfigured guard).

The list is fetched lazily at schema-render time so config() is read after the host app has finished booting. The catalog comes from Martis\Auth\GuardCatalog, which exposes available(): list<string> and default(): string for advanced uses.

MultiSelect

Type identifier: multi_select Extends: Field File: src/Fields/MultiSelect.php

Version note. Martis v2.0 and later read options() as [value => label], Nova's order; Martis v1.x read [label => value]. On v1.x, flip the arrays in the examples below, or upgrade: see Upgrading.

Multi-value select with chips/tags UI. Stores as JSON array.

MultiSelect::make('technologies')
    ->options([
        'php'    => ['label' => 'PHP', 'group' => 'Backend'],
        'python' => ['label' => 'Python', 'group' => 'Backend'],
        'react'  => ['label' => 'React', 'group' => 'Frontend'],
        'vue'    => ['label' => 'Vue', 'group' => 'Frontend'],
    ])
    ->displayUsingLabels()
    ->required()

Storage format: JSON array, e.g. ["php","react"] Overrides: resolve() decodes JSON/array to list; fill() writes the list, JSON-encoded unless the attribute carries an array / json / class cast that serialises it itself (see Structured values and Eloquent casts). Extra attributes: options, displayLabels

Date

Type identifier: date Extends: Field File: src/Fields/Date.php

Date picker (date-only by default).

Date::make('published_at', 'Published')
    ->withTime()          // enable date+time mode
    ->format('d/m/Y')     // custom display format
    ->nullable()
    ->sortable()

Overrides: resolve() normalizes Carbon/DateTime to formatted string. Extra attributes: withTime, displayFormat

Display: the index and detail pages show the date in the user's Martis locale, not the browser's (v2.1.0): 27/09/2026 for pt_PT, 9/27/2026 for en_US. A value format() turned into another string is shown as sent.

DateTime

Type identifier: datetime Extends: Date File: src/Fields/DateTime.php

Date + time picker. Extends Date; inherits all Date methods.

DateTime::make('created_at', 'Created')
    ->hideFromForms()
    ->sortable()

Specific methods: None (inherits withTime(), format() from Date).

Display: the date and time in the user's Martis locale (v2.1.0).

Input: a calendar with a 24-hour time picker. The hour and minute can be typed (digits, then the arrow keys or the up/down buttons to step; values wrap around). Before v2.16.4 they could only be changed with the buttons.

Email

Type identifier: email Extends: Text File: src/Fields/Email.php

Email input with automatic email validation rule.

Email::make('email')
    ->sortable()
    ->searchable()
    ->required()
    ->unique(['users', 'email'], 'This email is already in use.')

Overrides: buildRules() appends 'email' to validation rules. Specific methods: None (inherits from Text).

Password

Type identifier: password Extends: Field File: src/Fields/Password.php

Password field. Hashes value with bcrypt, never exposes hashes.

Password::make('password')
    ->nullable()
    ->withStrengthMeter()

Default overrides:

• showOnIndex = false
• showOnDetail = false

Overrides:

• resolve() always returns null (never expose password hashes).
• fill() hashes with Hash::make(). Skips empty/null values (no update if blank). A fillUsing() callback takes the write over and receives the plain value (hashing is then its decision); an empty value never reaches it. Its value is never stored in the action event log either: an action's Password field is logged as ******.

Specific methods:

• withStrengthMeter(bool $enabled = true): static — ⭐ Martis extension. Shows a 0–4 strength meter below the input (length + character-class heuristic). Pairs naturally with PasswordConfirmation to share the same UI cue. No extra dependency — zxcvbn-lite is inlined in the React component.

Declarative complexity requirements (⭐ Martis extension):

Each requirement method adds a matching Laravel validation rule AND publishes to the frontend so the showRequirements() checklist can tick in real time.

• minLength(int $length): static — minimum length. Adds min:N.
• requireUppercase(bool $value = true): static — adds regex:/\p{Lu}/u.
• requireLowercase(bool $value = true): static — adds regex:/\p{Ll}/u.
• requireNumber(bool $value = true): static — adds regex:/\pN/u.
• requireSymbol(bool $value = true): static — adds regex:/\p{Z}|\p{S}|\p{P}/u.
• defaultRules(bool $value = true): static: validates with the app's Password::defaults() and shows its requirements in the checklist (v2.3.0), as Nova's generated User resource validates with Password::default(). The server enforces the policy and the field's own requirements together, so the checklist shows the stricter of the two minimums. On a resource that creates and updates users, require it on create and leave it optional on update, as Nova's User resource does: ->creationRules(['required'])->updateRules(['nullable']); a blank update keeps the current password.
• disallowCommonPasswords(bool $value = true): static — rejects a small inline list (password, qwerty, 12345…, letmein, admin, welcome, abc123, iloveyou) via a closure rule.
• showRequirements(bool $value = true): static — opt-in. Renders the ✓/✗ checklist under the strength meter. When every requirement passes, the meter is clamped to at least "Good" (score ≥ 3) so "all checks green" never reads as "Weak".

The uppercase, lowercase, number and symbol checks are those of Laravel's Password rule (v2.3.0): an accented capital is uppercase, an accented letter is not a symbol, and lengths count characters.

Example:

Password::make('password')
    ->withStrengthMeter()
    ->minLength(10)
    ->requireUppercase()
    ->requireNumber()
    ->requireSymbol()
    ->disallowCommonPasswords()
    ->showRequirements()

Or follow the app's policy (v2.3.0):

Password::make('password')
    ->defaultRules()
    ->creationRules(['required'])
    ->updateRules(['nullable'])
    ->withStrengthMeter()
    ->showRequirements()

PasswordConfirmation

Type identifier: password_confirmation Extends: Field File: src/Fields/PasswordConfirmation.php

Companion field for a paired Password. Never persists to the model — relies on Laravel's confirmed rule on the password field for validation.

Password::make('password')
    ->creationRules(['required', 'confirmed', 'min:8'])
    ->withStrengthMeter(),
 
PasswordConfirmation::make('password_confirmation')
    ->confirms('password')

Default overrides:

• showOnIndex = false
• showOnDetail = false
• fill() is a no-op (companion fields never hydrate the model).
• resolve() always returns null.

Specific methods:

• confirms(string $attribute): static — Name the paired password attribute (default: 'password'). Matches Laravel's confirmed rule convention.

⭐ Martis extensions (UI, automatic):

• Live match indicator — green tick / red cross the moment the two inputs match or diverge.
• Shared strength meter — if the paired Password field has withStrengthMeter(), the meter is shared.
• Synchronized visibility toggle — eye icons on both inputs mirror each other.

Slug

Type identifier: slug Extends: Field File: src/Fields/Slug.php

URL-safe identifier auto-generated from a source attribute.

Slug::make('slug')
    ->from('title')                                // source attribute
    ->separator('-')                               // default: '-'
    ->reserved(['admin', 'api', 'login'])          // rejected values
    ->lockAfter(fn ($post) => $post->is_published) // freeze after publish
    ->withinIndexScope()                           // probe uniqueness per tenant (see below)

Specific methods:

• from(string $attribute): static — Source attribute to slugify.
• separator(string $separator): static — Token separator (default: '-').
• reserved(array $reserved): static — ⭐ Martis extension. Reject these exact values (system paths). Validation emits slug_reserved error; the /slug-check endpoint returns { reserved: true, suggestion }.
• lockAfter(Closure $condition): static — ⭐ Martis extension. Freezes the slug on existing records once the condition holds. Slug::fill() becomes a no-op in that case — SEO protection.
• withinIndexScope(bool $within = true): static — ⭐ Martis extension. Run the slug-check uniqueness probe through the resource's scopes() and indexQuery() instead of the whole table. Enable it when uniqueness is per tenant or per owner (a composite unique index such as tenant_id, slug), so the check answers for the records the user can list and never reveals that a slug exists in another scope. See Live collision detection.
• badgeVariant(string $variant): static — Read-only display badge variant. Accepts 'default' (alias 'muted'), 'accent', 'success', 'warning', 'danger', 'custom'. Unknown values fall back to 'default'.
• badgeAccent(): static — Sugar for badgeVariant('accent'). Reads cleanly when the slug IS the row identity (Permission name, Role name).
• badgeColor(string $color): static — Custom CSS colour for the badge. Accepts any browser-recognised colour (hex, rgb(), hsl(), oklch(), named). The frontend tints the background as a 14% mix with the surface so it stays subtle in both themes; the foreground uses the colour verbatim. Implies badgeVariant('custom').
• generate(string $value): string — Unicode-safe slugify ("São Paulo" → "sao-paulo"). Exposed for tests/controllers.
• isLockedFor(?Model $model): bool — Query the lock condition directly.

⭐ Martis extensions (UI, automatic):

• Live preview — the React input regenerates the slug as the user types in the source field (i18n-aware transliteration), until the slug is edited by hand. On a create form, a replicated record included, the slug follows the source from the source's first change, as in Nova: the slug the form opens with, copied or empty, stays until then (v1.38.0+). On an edit form (the update page or the update drawer) a stored slug counts as set: changing the source leaves it alone, so renaming a record does not silently change its URL, and an empty stored slug follows the source at once. Edit the slug directly, or clear it (a nullable() slug shows a clear button) to regenerate it from the source and follow it again. A slug the user empties by hand stays empty while the source has text, and follows the source again once the source is empty too, so the next record's slug follows its title after "Create & add another" (v1.38.0+). Before v1.38.0 a create form took a slug it opened with for one set by hand, so a replicated slug never followed the title, and filled an empty slug from a source that already had text.

• Live collision detection — debounced probe against GET /martis/api/resources/{resource}/slug-check/{field}?value=…&id=…. Response envelope:

  \{
    "data": \{
      "available": false,
      "reserved": false,
      "suggestion": "existing-post-2"
    }
  }

  The UI renders a clickable suggestion when suggestion is non-null. The check uses the Slug declared on the form it comes from: fieldsForUpdate() when id names a record the user may update (authorizedToUpdate()), otherwise fieldsForCreate() and then fieldsForInlineCreate(), then fields(). A Slug declared on one form only is found, and that declaration's separator() and reserved() apply (v1.38.0: the check read fields() first and never the inline-create form). The record being edited is left out of the uniqueness probe, so its own slug reads as available; an id the user may not update is answered like one that names no record (v1.38.0: any record id named was bound and left out of the probe, which told the slug of a record the user could not edit apart).

  The check answers whether a slug is taken, so it needs the ability to write one, not viewAny alone: authorizedToUpdate() on the record id names, otherwise authorizedToCreate() (a user who may only list the resource gets 403, for any id, so it cannot be used to test which slugs exist; before v2.4.0 viewAny was enough). The probe reads the whole table by default, which is right for a slug that is unique across it (a plain unique index): the answer then reflects records in every tenant or owner scope, including ones the user cannot list, exactly as saving the slug would, so a user who may create or update records can learn that a slug exists elsewhere. Where the host scopes records per tenant and the slug is unique per tenant, declare the field ->withinIndexScope(): the probe (and its -2, -3 suggestions) then runs through the resource's scopes() and indexQuery() and only the records the user can list count as taken.

Validation: a closure rule verifies the submitted value is already in its slugified form (so the server rejects mismatched case / spaces) and that it is not in the reserved list.

Timezone

Type identifier: timezone Extends: Field File: src/Fields/Timezone.php

Dropdown of every IANA timezone PHP knows about, grouped by continent.

Timezone::make('timezone')->default('Europe/Lisbon')

Specific methods:

• Timezone::groupedList(): array — Static. Returns ['Europe' => ['Europe/Lisbon', …], 'America' => [...], …].

⭐ Martis extensions (UI, automatic):

• Live current time — every option in the dropdown shows the zone's current local time and UTC offset. Ticks once a minute while the dropdown is open.
• Auto-detect button — "Use my timezone" reads Intl.DateTimeFormat().resolvedOptions().timeZone and fills the field.
• Grouped + filterable — Europe, America, Asia, … optgroups. The filter matches label, value, or offset (+01:00).

Icon

Type identifier: icon Extends: Field File: src/Fields/Icon.php

⭐ Martis differential — the Icon field offers three modes, one visual output (Phosphor icon).

// Mode A — display-only (no DB column)
Icon::make('marker', 'rocket')->color('success')
 
// Mode B — stored in a DB column, with ⭐ visual picker
Icon::make('industry_icon')
    ->stored()
    ->palette(['rocket', 'buildings', 'briefcase', 'globe'])
    ->colorFrom('brand_color')
    ->size(20)
 
// Mode C — computed from the model
Icon::make('state')->icon(fn ($model) => $model->is_active ? 'check' : 'x')

Factory:

• Icon::make(string $attribute, ?string $fixedIcon = null, ?string $label = null) — when $fixedIcon is set, the field is display-only (Mode A) until ->stored() flips it.

Specific methods:

• stored(bool $value = true): static — flip to Mode B. The icon name lives in the DB column named $attribute. Forms show a ⭐ visual picker.
• color(string $color): static — sets the icon tint. Accepts:
  • semantic tokens: success, warning, danger, info, muted, accent
  • CSS variables: var(--my-color)
  • arbitrary CSS: hex (#ec4899), rgb, named (red)
• colorFrom(string $attribute): static — read the color per-record from a sibling column on the same model (e.g. brand_color). Overrides ->color() when that column has a value; falls back to ->color() when empty.
• map(array $map): static — declarative value→icon(+color) mapping for stored fields. Accepts shortcut ['value' => 'iconName'] or full ['value' => ['icon' => '…', 'color' => '…']].
• palette(array $palette): static — whitelist for the picker. fill() silently drops values outside the palette — the DB never stores an icon the UI refuses to render.
• size(int $size): static — render size in pixels (clamped 8–64; default 16).
• icon(Closure $resolver): static — Mode C. Callback receives the model and returns string or ['icon' => '…', 'color' => '…'].

Behavioural notes:

• Mode A defaults to showOnForms = false. ->stored() re-enables form exposure.
• fill() is a no-op for Mode A / Mode C — only Mode B hydrates the model. Mode B respects readonly() (a closure is evaluated per request, so readonly(fn ($request) => ! $request->user()->isAdmin()) locks the write too, not only the input) and fillUsing(), as every field does.
• Index rendering respects size() — put a small Icon at the start of fieldsForIndex() to get a visual marker on each row.

Stack + Line

Type identifier: stack / line Extends: Field File: src/Fields/Stack.php, src/Fields/Line.php

Composite display field — renders a vertical stack of styled text lines as a single cell/detail slot. Ideal for compressing identity columns (name + email + company) into a single column without writing a custom component.

Stack::make('identity', __('fields.identity'), [
    Line::make('name')->asHeading()->subtitleFrom('email'),
    Line::make('company')->asMuted(),
])->divider();

Calling styles:

Stack::make('identity', [Line::make('name'), Line::make('email')]);            // attribute + lines
Stack::make('identity', 'Identity', [Line::make('name')]);                    // attribute + label + lines

Line API — style variants:

Stack API:

⭐ Martis differentials:

1. Works on the index. Martis renders Stack as an index-table cell, perfect for identity columns.
2. ->asCode() variant — monospace styling for slugs, hashes, tokens.
3. Line::subtitleFrom('attribute' | Closure) — one-line sugar to emit a muted secondary row without declaring a second Line. Accepts a Closure receiving the model for derived subtitles.
4. Stack::divider() — thin --martis-border separator between Lines; great for metadata listings.

Payload shape (per row)

The Stack emits { __martisStack: true, entries: [{ text, variant, subtitle }], divider }. The frontend StackField component detects the wrapper and renders each entry with the appropriate .martis-line-* class. Custom themes restyle every Line in the package by overriding the CSS variables used inside .martis-line-heading/base/small/muted/code.

Url

Type identifier: url Extends: Field File: src/Fields/Url.php

URL field with clickable link on index/detail and url validation. A stored value is a link only when the browser itself reads it as a web URL, a path, mailto: or tel: (v2.4.0: the same check the sidebar uses, so java<TAB>script: and other padded schemes are not links); anything else is shown as plain text.

Url::make('website')
    ->displayText('Visit Website')
    ->nullable()

Overrides: buildRules() appends 'url' to validation rules. Extra attributes: displayText

Color

Type identifier: color Extends: Field File: src/Fields/Color.php

HTML5 color picker. Stores hex string (e.g. #ff5733).

Color::make('brand_color', 'Brand Color')

Specific methods: None (all from base). Extra attributes: None.

Country

Type identifier: country Extends: Field File: src/Fields/Country.php

ISO 3166-1 alpha-2 country picker. Stores 2-letter code (e.g. US, BR).

Country::make('country')
    ->withFlags()     // show emoji flags
    ->searchable()

Extra attributes: countries, showFlags

Currency

Type identifier: currency Extends: Number File: src/Fields/Currency.php

Monetary value input with currency formatting. Inherits min(), max(), step(), integer() from Number.

use Martis\Enums\CurrencyCode;
use Martis\Enums\CurrencyDisplayMode;
 
Currency::make('price')
    ->currency(CurrencyCode::EUR)
    ->asMinorUnits()                                  // stored as cents
    ->displayMode(CurrencyDisplayMode::BadgeText)
    ->badgeColor('green')

Supported currencies: USD, EUR, GBP, BRL, JPY, CNY, CAD, AUD, CHF, INR, MXN, KRW, SEK, NOK, DKK, PLN, THB, ZAR, TRY, RUB, NZD, SGD, HKD, CLP, ARS, COP, PEN Extra attributes: currencyCode, currencySymbol, currencyName, currencyDecimals, locale, minorUnits, displayMode, badgeColor + Number extras (min, max, step)

Display and input: the amount uses the separators of the user's Martis locale, unless locale() sets one, on the index, the detail page and the form input (v2.1.0). The locale extra attribute is present only when locale() was called.

BelongsTo

Type identifier: belongs_to Extends: Field File: src/Fields/BelongsTo.php

Many-to-one relationship field. Stores foreign key, displays related model title.

Which title (v2.17.0). Without titleAttribute(), the field shows the related resource's title(), as Nova does and as its own picker already did: a ContactResource whose titleAttribute() is label (or that overrides title()) labels the cell, the detail page and the edit form the way it labels the picker row. Before v2.17.0 the field read name and ignored the related resource, so a model without a name column showed #4. A related resource left on the base id default keeps name, as before, and an explicit titleAttribute() / displayColumn() always wins. Tag, BelongsToMany and MorphToMany follow the same rule.

// Recommended: pass FK column (auto-detects relationship via _id suffix)
BelongsTo::make('user_id', 'Author')
    ->relatedResource('users')
    ->titleAttribute('name')
    ->sortable()
 
// Alternative: pass relationship name
BelongsTo::make('user', 'Author')
    ->relatedResource('users')

For many-to-many relationships use BelongsToMany, MorphToMany, or Tag — BelongsTo itself is single-cardinality. Since v1.38.0 a multiple key on its definition (withMeta(['multiple' => true])) changes nothing; before, it switched the input to a multi-select left over from the multiple() method removed in April 2026, which sent a list of ids that fill() stored as an empty foreign key.

// Inline create — show "+" button to create related record in a modal
use Martis\Enums\ModalSize;
 
BelongsTo::make('category_id', 'Category')
    ->relatedResource('categories')
    ->showCreateRelationButton()
    ->modalSize(ModalSize::Large)

Where the picker loads its options

The BelongsTo, MorphTo and Tag pickers list their options from the relatable endpoint of what declares the field, so that declaration (related resource, relatableQueryUsing(), withoutTrashed()) and the relatable hooks apply:

Each is gated like the surface it serves (the form, running the Action, the attach or the pivot update), then on viewAny of the related resource. See Relationships → Relation fields declared on one form only, Relation pickers among the pivot fields and Repeater → Relation pickers and remote selects in rows.

Before v1.38.0 a picker among a relationship's pivot fields or in a Repeater row asked the page's resource for the attribute, which its forms do not declare: 404 and an empty picker.

Peek / Preview

The peek card appears when the user hovers the small preview icon next to a related record link. Content is fetched lazily from the related resource's fieldsForPreview().

The icon is the only trigger; hovering the record link itself does not open the peek card.

The card is at most 20rem wide. A long title or value wraps onto more lines inside it; the card takes no pointer events, so nothing in it is cut off with an ellipsis (v2.16.2; before, a value longer than 12rem was truncated and could not be read).

// Peek is enabled by default
BelongsTo::make('author_id', 'Author')
    ->relatedResource('users')
 
// Disable peek entirely
BelongsTo::make('author_id')->noPeeking()
 
// Equivalent
BelongsTo::make('author_id')->peekable(false)

The peek card content is governed by the related resource's fieldsForPreview() method, which defaults to the detail fields (fieldsForDetail()). Override it on the resource class to control exactly which fields appear in the peek card:

// UserResource.php (or any resource)
public function fieldsForPreview(Request $request): array
{
    return [
        Text::make('Name'),
        Text::make('Email'),
        Text::make('Role'),
    ];
}

Fields can also be shown/hidden from preview individually. By default a field visible on detail is also visible in preview (showOnPreview falls back to showOnDetail).

Overrides:

• resolve() returns {id, title} for the related record.
• fill() sets the foreign-key column on the parent model.

Extra attributes: relationship, foreignKey, titleAttribute, relatedResource, relatedLabel, relationSearchable, displayAsLink, showCreateRelationButton, modalSize, peekable, placeholder, iconColor

Toolbar controls (inherited)

All nine hideXxx() setters from ControlsRelationshipToolbar are inherited — see relationships.md § Toolbar hide flags. On BelongsTo only the Create button (inline create) and the View action surface are affected (per the trait scope matrix). Remember: visible = authorized AND NOT hidden. Authorization is always the source of truth; the hide flags can only hide, never force-visible. src/Fields/Concerns/ControlsRelationshipToolbar.php

Tag

Type identifier: tag Extends: Field File: src/Fields/Tag.php

Relational tagging via BelongsToMany. Renders as tag chips with autocomplete.

Tag::make('tags', 'Tags')
    ->relatedResource('tags')
    ->titleAttribute('name')
    ->withPreview()
    ->displayAsList()
    ->showCreateRelationButton()
    ->modalSize('3xl')
    ->preload()

Preview (v1.38.0+): with withPreview() a tag on the index and detail pages opens the peek card of its record after a short hover: the related resource's fieldsForPreview(), the card a BelongsTo shows (see Peek / Preview). Before v1.38.0 the method only serialised the flag and nothing opened.

Inline create (v1.38.0+): with showCreateRelationButton() the picker's dropdown ends with a Create entry that opens the related resource's inline-create modal (its fieldsForInlineCreate(), sized by modalSize()), and the record it creates joins the selection. The entry follows the related resource's policy (the schema serialises showCreateRelationButton: false when the user may not create a record there), is absent on a readonly field, and never shows on a Tag inside another inline-create form. Before v1.38.0 the method only serialised the flag: the picker offered no way to create a tag.

Overrides:

• resolve() loads related models, returns [{id, title}].
• fill() registers deferred pivot sync via DeferredRelationSync.

Extra attributes: relationship, titleAttribute, relatedResource, withPreview, displayAsList, showCreateRelationButton, modalSize, preload, relationSearchable

Toolbar controls (inherited)

Tag renders a chip/autocomplete UI of its own and does not use the shared RelationshipTableShell, so the ControlsRelationshipToolbar trait is not applied here. Use BelongsToMany when you need the full DataTable toolbar with hide flags, search, per-page, and soft-delete dropdown.

BelongsToMany

Type identifier: belongs_to_many Extends: Field File: src/Fields/BelongsToMany.php

Full many-to-many pivot relationship field. Renders as a DataTable panel on the detail page with attach/detach, pivot field editing, search, sort, and pagination. On the index page, shows a count badge.

Where it shows — the detail page and the update form; hidden from index (->showOnIndex() displays the count badge). Never on a create form (the create page, the create drawer, the inline-create modal): a pivot row needs the key of the record, which does not exist yet, so, like Nova, no visibility call (showOnCreating(), showOnForms(), onlyOnForms()) brings the field there. Attach once the record exists, or use Tag to pick related records while creating.

Since v1.38.0. Before it, showOnCreating() put the panel on the create forms, where it asked /api/resources/{resource}//belongs-to-many/{relationship} (404) on the create page, and listed, and attached to, the page's record in a create drawer or an inline-create modal opened over another record (a Replicate drawer, for instance, attached to the record it copies).

// Minimal usage
BelongsToMany::make('Tags')
    ->relatedResource('tags')
 
// Full API
BelongsToMany::make('Tags', 'tags', TagResource::class)
    ->searchable()
    ->collapsable()
    ->collapsedByDefault()
    ->allowDuplicateRelations()
    ->showCreateRelationButton()
    ->modalSize('3xl')
    ->withSubtitles()
    ->dontReorderAttachables()
    ->relatableQueryUsing(fn ($request, $query) => $query->where('active', true))
    ->fields(fn () => [
        Text::make('notes', 'Notes')->nullable(),
        Date::make('expires_at', 'Expires At')->nullable(),
    ])
    ->actions(fn () => [
        ExtendExpiry::make(), // runs on the selected rows, see actions.md § Pivot Actions
    ])
    ->perPage(15)
    ->canAttach(true)
    ->canDetach(true)

API Endpoints

A relation picker among the pivot fields asks the panel (the two pivot-fields routes), gated like the panel and then like the attach (attachAny{Model}) or the pivot update (updatePivot{Model}). See Relationships → Relation pickers among the pivot fields.

The detach and the pivot update answer 404 for a {relatedId} that is not attached to the parent, with the body of an id that does not exist (v2.11.1). See Relationships → Only an attached record is detached.

Authorization

Override authorizedToAttach() or authorizedToDetach() on your Resource to restrict operations:

public function authorizedToAttach(Request $request, Model $related): bool
{
    return $request->user()?->isAdmin() ?? false;
}
 
public function authorizedToDetach(Request $request, Model $related): bool
{
    return $request->user()?->isAdmin() ?? false;
}

Without an override they ask the parent's policy (attach{Model}, detach{Model}; permitted when the policy does not define them). attachAny{Model} (authorizedToAttachAny()) gates the attach as a whole: when it denies, the list of records to attach, the attach and the attach modal's pivot pickers answer 403 (v1.38.0+). See Relationships → Authorization.

Overrides:

• resolve() returns null on the detail page (data is loaded via API endpoints), or the count (integer) when shown on index.
• fill() is a no-op — attach/detach is handled exclusively via the dedicated API endpoints.

Extra attributes: relationship, relatedResource, titleAttribute, searchable, collapsable, collapsedByDefault, allowDuplicateRelations, showCreateRelationButton, modalSize, withSubtitles, dontReorderAttachables, pivotFields, belongsToManyMeta

Toolbar controls (inherited)

All nine hideXxx() setters from ControlsRelationshipToolbar are inherited — see relationships.md § Toolbar hide flags. On many-to-many fields, hideCreateButton() hides the Attach button and hideDeleteAction() hides the Detach variant. Remember: visible = authorized AND NOT hidden. Authorization is always the source of truth; the hide flags can only hide, never force-visible. src/Fields/Concerns/ControlsRelationshipToolbar.php

HasOne

Type identifier: has_one Extends: Field File: src/Fields/HasOne.php

One-to-one relationship. Renders a single related record panel on the detail page with optional Create / Edit / Delete controls. Detail-only by default — hidden from index and forms.

use Martis\Fields\HasOne;
 
HasOne::make('Profile', 'profile', ProfileResource::class)
    ->canCreate()
    ->canUpdate()
    ->canDelete(false)

Static factory HasOne::ofMany($name, $relationship, $resourceClass) promotes a hasMany()->latestOfMany() relation into a HasOneOfMany field. src/Fields/HasOne.php

Toolbar controls (inherited)

All nine hideXxx() setters from ControlsRelationshipToolbar are inherited — see relationships.md § Toolbar hide flags. HasOne renders no toolbar, so only the action hide flags (hideViewAction / hideEditAction / hideDeleteAction) have a visible effect per the trait scope matrix. Remember: visible = authorized AND NOT hidden. Authorization is always the source of truth; the hide flags can only hide, never force-visible.

See relationships.md — HasOne for the full guide.

HasOneOfMany

Type identifier: has_one_of_many Extends: HasOne File: src/Fields/HasOneOfMany.php

Promotes a hasMany()->latestOfMany() (or ->ofMany(col, aggregate)) relationship so the admin displays the latest / oldest record as if it were a plain HasOne. Ships an optional metric tile via aggregateVia() and a "latest of N" pill next to the panel heading.

use Martis\Enums\AggregateFunction;
use Martis\Fields\HasOneOfMany;
 
HasOneOfMany::make('Latest Invoice', 'latestInvoice', InvoiceResource::class)
    ->latestByTimestamp('paid_at')
    ->aggregateVia(AggregateFunction::Sum, 'amount');

src/Fields/HasOneOfMany.php

Toolbar controls (inherited)

All nine hideXxx() setters from ControlsRelationshipToolbar are inherited (via HasOne) — see relationships.md § Toolbar hide flags. Only the action hide flags (hideViewAction / hideEditAction / hideDeleteAction) have a visible effect on this single-record panel. Remember: visible = authorized AND NOT hidden. Authorization is always the source of truth; the hide flags can only hide, never force-visible.

See relationships.md — HasOneOfMany for the full guide.

HasOneThrough

Type identifier: has_one_through Extends: HasOne File: src/Fields/HasOneThrough.php

Shows a single distant record reached through an intermediate model (hasOneThrough). As in Nova, no Create: canCreate() has no effect and the has-one endpoints refuse a create through a hasOneThrough relationship with a 403, whichever field declares it. Edit and Delete work as on HasOne (see relationships.md § HasOneThrough).

use Martis\Fields\HasOneThrough;
 
HasOneThrough::make('Account Manager', 'accountManager', TeamMemberResource::class)
    ->throughBreadcrumb();

src/Fields/HasOneThrough.php

Toolbar controls (inherited)

All nine hideXxx() setters from ControlsRelationshipToolbar are inherited — see relationships.md § Toolbar hide flags. Because a Through field never offers Create, hideCreateButton() is redundant; the other hideXxx() setters work as on HasOne. Remember: visible = authorized AND NOT hidden. Authorization is always the source of truth; the hide flags can only hide, never force-visible.

See relationships.md — HasOneThrough for the full guide.

HasMany

Type identifier: has_many Extends: Field File: src/Fields/HasMany.php

One-to-many relationship. Renders an inline DataTable panel on the detail page with full inline CRUD (create, edit, delete), search, sort, per-page, and pagination via RelationshipTableShell. Detail-only by default — use ->showOnIndex() to display a count badge on index. The count, like the panel, includes only the records the related resource's index lists (its scopes() and indexQuery(), v2.0), and the index computes it for the whole page in its own query. That query resolves the relationship as Laravel's withCount() and eager loading do, on a model that holds no record: a relationship method that reads the parent's attributes gets null there. One that throws without its record is counted on each row instead; one that reads null counts the wrong rows, so a relationship counted on the index should not depend on the parent's attributes.

use Martis\Fields\HasMany;
use Martis\Enums\HasManyIndexDisplay;
use Martis\Enums\HasManyRedirectMode;
 
HasMany::make('Comments', 'comments')
    ->relatedResource('comments')
    ->collapsable()
    ->collapsedByDefault()
    ->perPage(15)
    ->showRelationCount()
    ->redirectAfterSave(HasManyRedirectMode::Parent);

src/Fields/HasMany.php

Toolbar controls (inherited)

All nine hideXxx() setters from ControlsRelationshipToolbar are inherited — see relationships.md § Toolbar hide flags. On HasMany the full surface is affected (search / create / per-page / soft-delete dropdown + view / edit / delete / restore / force-delete). Remember: visible = authorized AND NOT hidden. Authorization is always the source of truth; the hide flags can only hide, never force-visible.

See relationships.md — HasMany for the full guide and Relationship panel anatomy for the shared shell layout.

HasManyThrough

Type identifier: has_many_through Extends: HasMany File: src/Fields/HasManyThrough.php

Inline DataTable of many records reached through an intermediate (hasManyThrough). As in Nova, no Create: canCreate() has no effect and the has-many endpoints refuse a create through a hasManyThrough relationship with a 403, whichever field declares it. The rows keep View / Edit / Delete / Restore / Force delete as on HasMany (see relationships.md § HasManyThrough).

use Martis\Fields\HasManyThrough;
 
HasManyThrough::make('Managed Projects', 'managedProjects', ProjectResource::class)
    ->throughBreadcrumb()
    ->countBadge();

src/Fields/HasManyThrough.php

Toolbar controls (inherited)

All nine hideXxx() setters from ControlsRelationshipToolbar are inherited (via HasMany) — see relationships.md § Toolbar hide flags. Since the field never offers Create, hideCreateButton() is redundant; the other hideXxx() setters work as on HasMany (search / per-page / soft-delete dropdown + view / edit / delete / restore / force-delete). Remember: visible = authorized AND NOT hidden. Authorization is always the source of truth; the hide flags can only hide, never force-visible.

See relationships.md — HasManyThrough for the full guide.

MorphOne

Type identifier: morph_one Extends: Field File: src/Fields/MorphOne.php

Polymorphic one-to-one relationship (morphOne). Same UI as HasOne but for polymorphic relations. Detail-only by default.

use Martis\Fields\MorphOne;
 
MorphOne::make('Thumbnail', 'thumbnail', ThumbnailResource::class)
    ->canCreate()
    ->canUpdate();

src/Fields/MorphOne.php

Toolbar controls (inherited)

All nine hideXxx() setters from ControlsRelationshipToolbar are inherited — see relationships.md § Toolbar hide flags. Same scope as HasOne: only the action hide flags have a visible effect. Remember: visible = authorized AND NOT hidden. Authorization is always the source of truth; the hide flags can only hide, never force-visible.

See relationships.md — MorphOne for the full guide.

MorphOneOfMany

Type identifier: morph_one_of_many Extends: MorphOne File: src/Fields/MorphOneOfMany.php

Polymorphic counterpart of HasOneOfMany. Promotes a morphMany()->latestOfMany() (or ->ofMany(col, aggregate)) relationship.

use Martis\Enums\AggregateFunction;
use Martis\Fields\MorphOneOfMany;
 
MorphOneOfMany::make('Latest Note', 'latestNote', NoteResource::class)
    ->latestByTimestamp()
    ->aggregateVia(AggregateFunction::Count, '*');

src/Fields/MorphOneOfMany.php

Toolbar controls (inherited)

All nine hideXxx() setters from ControlsRelationshipToolbar are inherited (via MorphOne) — see relationships.md § Toolbar hide flags. Only the action hide flags have a visible effect on this single-record panel. Remember: visible = authorized AND NOT hidden. Authorization is always the source of truth; the hide flags can only hide, never force-visible.

See relationships.md — MorphOneOfMany for the full guide.

MorphMany

Type identifier: morph_many Extends: Field File: src/Fields/MorphMany.php

Polymorphic one-to-many relationship (morphMany). Same DataTable UI as HasMany — full inline CRUD, search, sort, per-page, pagination — via RelationshipTableShell. Detail-only by default.

use Martis\Fields\MorphMany;
 
MorphMany::make('Comments', 'comments', CommentResource::class)
    ->collapsable()
    ->collapsedByDefault()
    ->perPage(10)
    ->canCreate(false);