moonshine-fields-v3

name: moonshine-fields-v3 description: Use when working with any MoonShine v3 field type, relationship fields, field validation, field lifecycle, custom apply logic, field modes, or creating custom fields.

MoonShine v3 Fields

Field Concept

Fields are the core building blocks of the MoonShine admin panel. They are used in:

• FormBuilder for building forms
• TableBuilder for creating tables
• ModelResource for filters
• Custom pages and Blade views

Every field is created via the static make() method:

use MoonShine\UI\Fields\Text;

Text::make('Title')           // label only, column auto-detected as "title"
Text::make('Title', 'title')  // explicit label + column
Text::make('Title', 'first_name', fn($item) => $item->first_name . ' ' . $item->last_name) // with formatted callback

Constructor signature for all fields:

make(Closure|string|null $label = null, ?string $column = null, ?Closure $formatted = null)

Fields in MoonShine are NOT tied to a model (except Slug and relationship fields).

Field Modes

Every field has three visual states:

Text::make('Title')->defaultMode()  // always form element
Text::make('Title')->previewMode()  // always preview display
Text::make('Title')->rawMode()      // always raw value

Field Lifecycle

In FormBuilder (saving)

1. Field declared in resource
2. Field enters FormBuilder
3. FormBuilder fills the field (fill())
4. FormBuilder renders the field
5. On submit: beforeApply() -> apply() -> model save() -> afterApply()

In TableBuilder (display)

1. Field enters TableBuilder in preview mode
2. TableBuilder iterates data, fills each field
3. TableBuilder renders rows with field previews

In Export

1. Field enters Handler in raw mode
2. Handler iterates data, fills fields, generates table from raw values

Apply Lifecycle

Fields modify incoming data during the "apply" phase. For model saving:

Text::make('Thumbnail by link', 'thumbnail')
    ->onApply(function(Model $item, $value, Text $field) {
        if ($value) {
            $item->thumbnail = Storage::put('thumbnail.jpg', file_get_contents($value));
        }
        return $item;
    })

For filters (QueryBuilder):

Text::make('Title')
    ->onApply(function(Builder $query, mixed $value, Text $field) {
        $query->where('title', $value);
    })

Related methods: onBeforeApply(), onAfterApply(), canApply().

Quick Reference: All Field Types

Basic Input Fields

Selection Fields

File & Editor Fields

Structural Fields

Relationship Fields

Relationship Fields Overview

All relationship fields require a registered ModelResource. Constructor:

BelongsTo::make(
    Closure|string $label,
    ?string $relationName = null,      // auto-detected from label via camelCase
    Closure|string|null $formatted = null, // display column or closure
    ModelResource|string|null $resource = null, // auto-detected from relation name
)

Key patterns across relationship fields:

• asyncSearch() - async search with custom query, formatted output, limit
• creatable() - create related object via modal
• valuesQuery() - modify the query that fetches dropdown values
• withImage() - add images to dropdown items
• searchable() - enable search in dropdown
• selectMode() - display BelongsToMany as dropdown instead of checkboxes
• relatedLink() - show as a link with count instead of full list
• tabMode() / modalMode() - display HasOne/HasMany in tabs or modals
• disableOutside() - render inside the main form instead of separately

Common Field Methods (All Fields)

Display & Attributes

->setLabel('New Label')       // change label
->translatable('ui')          // translate label
->hint('Helper text')         // add hint text
->badge('success')            // show as colored badge in preview
->horizontal()                // label and field side by side
->withoutWrapper()            // remove wrapper div
->sortable()                  // enable column sorting in tables
->required()                  // mark as required
->disabled()                  // disable input
->readonly()                  // read-only
->customAttributes(['class' => 'my-class'])
->customWrapperAttributes(['class' => 'mt-8'])

Value Modification

->default('value')            // default value
->nullable()                  // allow NULL
->fill('value')               // manually fill
->changeFill(fn($data, $ctx) => ...)  // modify fill logic
->afterFill(fn($ctx) => ...)          // post-fill logic
->changePreview(fn($value, $ctx) => ...) // custom preview
->changeRender(fn($value, $ctx) => ...)  // replace entire render
->modifyRawValue(fn($raw, $data, $ctx) => ...) // modify raw/export value
->fromRaw(fn($raw, $ctx) => ...)      // convert raw to value (import)

Apply Lifecycle

->onApply(fn($item, $value, $field) => $item)
->onBeforeApply(fn($item, $value, $field) => $item)
->onAfterApply(fn($item, $value, $field) => $item)
->canApply(fn() => false)     // skip apply entirely

Conditional Display

->canSee(fn($field) => true)          // show/hide conditionally
->when(fn() => true, fn($field) => $field->locked())
->showWhen('other_field', '=', 'value') // dynamic JS-based show/hide
->showWhenDate('created_at', '>', '2024-01-01')

Inline Editing (Preview Mode)

->updateOnPreview()           // edit in table cells
->withUpdateRow('table-name') // update entire row on change
->updateInPopover('table-name') // edit in popover

Reactivity

->reactive(function(Fields $fields, ?string $value): Fields {
    return tap($fields, fn($f) => $f->findByColumn('slug')?->setValue(str($value)->slug()->value()));
})

Creating a Custom Field

php artisan moonshine:field

This generates a field class with its own Blade view. Override resolvePreview(), resolveOnApply(), and the view to customize behavior.

Cross-References

• For how fields are used in resources, see the moonshine-resources-v3 skill
• Relationship fields require registered ModelResource instances
• Fields work with FormBuilder and TableBuilder components
• Filters use the same field classes with filter-specific apply logic

Reference Files

• references/basic-fields.md - Text, Number, Date, Slug, ID, and other basic input fields
• references/selection-fields.md - Select, Enum, Checkbox, Switcher
• references/file-fields.md - File, Image, Code, Markdown, TinyMCE editors
• references/relationship-fields.md - All relationship field types with patterns
• references/field-display-attributes.md - Display methods, view modes, and attribute configuration
• references/field-values-lifecycle.md - Value methods, fill logic, and apply lifecycle
• references/field-interactive.md - Conditional display, showWhen, inline editing, onChange, reactivity, custom fields