moonshine-fields-v4

name: moonshine-fields-v4 description: Use when working on MoonShine v4 field types, relationship fields, field validation, lifecycle, apply logic, field modes, reactivity, showWhen, or creating custom fields.

MoonShine v4 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)

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

Common Methods Quick Reference

Field Types Catalog

Basic Input Fields

Selection Fields

File and 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,
    Closure|string|null $formatted = null,
    ModelResource|string|null $resource = null,
)

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
• associatedWith() - link field values to another field with asyncOnInit support

v4 Changes from v3

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.

Reference Files

• references/basic-fields.md - Text, Number, Date, Slug, ID, Hidden, and other basic input fields
• references/selection-fields.md - Select (with Tom Select plugins, Options DTOs), Enum, Checkbox, Switcher, Preview
• references/file-fields.md - File, Image, Code, Markdown, TinyMCE editors
• references/relationship-fields.md - All relationship field types with full method reference
• references/field-display-attributes.md - Display methods, view modes, attributes, wrapper, sorting
• references/field-values-lifecycle.md - Value methods, fill logic, apply lifecycle, onChange, render
• references/field-interactive.md - Reactivity, showWhen, Json, Fieldset, Template, HiddenIds, inline editing, assets