# Highlights · Martis docs
> A tour of the surfaces Martis ships beyond the bare-essential admin-panel contract, each a first-class API of the package. They come with their own configuration, generators, or escape hatches, and each entry below links into the dedicated reference for the full surface.
Source: https://getmartis.com/docs/reference/differentials
# Highlights
A tour of the surfaces Martis ships beyond the bare-essential admin-panel contract, each a first-class API of the package. They come with their own configuration, generators, or escape hatches, and each entry below links into the dedicated reference for the full surface.
This page is descriptive: it tells you **what is in the box**. It does not benchmark Martis against any other package — for ecosystem comparisons see the project README.
## Override System
### Four-Tier Component Resolution
Replace any React component at the right granularity level without forking the package.
Resolution order (highest priority first):
1. **Explicit key** — `->component('my-custom-field')` on a specific field instance.
2. **Per-resource** — `componentRegistry.registerResourceFieldDisplay('users', 'status', MyStatusBadge)`.
3. **Global type** — `componentRegistry.registerFieldDisplay('select', MyCustomSelect)`.
4. **Built-in default** — the package's default component.
```
// PHP: set an explicit component key on a field
Text::make('bio')->component('rich-bio-display')
```
```
// TypeScript: register a custom component under `resources/js/martis-extensions/`
import { componentRegistry } from '@martis/runtime'
import { RichBioDisplay } from './components/RichBioDisplay'
componentRegistry.register('rich-bio-display', RichBioDisplay)
```
Full guide: [Override System](https://getmartis.com/docs/customization/overrides).
### Drawer CRUD (slide-in panels)
Render Create, Update, and Detail in a slide-out drawer instead of a full page. Reduces context switching and keeps the index visible.
```
public function overrides(): array
{
return [
'create' => DrawerOverride::make()
->width('520px')
->expandedWidth('800px')
->allowExpand()
->allowFullscreen()
->position('right'),
];
}
```
Slide animation, expand/collapse, fullscreen toggle, ESC to close, backdrop click, configurable width and position.
### Unsaved Changes Guard
Uniform protection against discarding unsaved edits across **every** surface — drawers and full-page create/update routes. Intercepts the close button, ESC, backdrop click, the browser back button, and in-app router links.
```
use Martis\UnsavedChangesConfig;
use Martis\Contracts\UnsavedChangesConfigContract;
public static function confirmUnsavedChanges(): bool|UnsavedChangesConfigContract
{
return UnsavedChangesConfig::make()
->title(__('projects.unsaved_title'))
->body(__('projects.unsaved_body'))
->icon('briefcase')
->iconColor('info')
->confirmLabel(__('projects.unsaved_discard'))
->confirmColor('danger')
->cancelLabel(__('projects.unsaved_keep'));
}
```
Return `false` (the default) to disable, `true` for the localised package defaults, or an `UnsavedChangesConfig` to override title, body, icon, colours and button labels. The same config applies whether the resource uses a drawer override or the page-based create/update flow.
**Implementation**
- **Browser back/forward** — a drawer pushes a history *sentinel* while it is open. A full-page form pushes one only once it has unsaved changes (v1.38.0+): a copy of the page's own history entry (same URL, same router `key` and `idx`) flagged as the guard's, so a clean form leaves the history alone and Back and Forward move between pages as anywhere else. Back from the sentinel lands on the page's entry, which a **capture-phase popstate listener** recognises and keeps from React Router with `stopImmediatePropagation()`, avoiding the v6 URL-flicker bug; every other pop belongs to the router, or to the modal or drawer on top. The sentinel is re-armed the moment the dialog opens, so repeated back presses while the dialog is visible stay trapped. On confirm the guard pops the re-armed sentinel (drawer: one `back()`; page: `go(-2)` for sentinel + real entry); changes saved since the sentinel was pushed let the back press carry on to the previous page. A page left with its sentinel on top (a save that redirects, a confirmed link) adopts that sentinel when Back returns to it, so the next Back walks past the page in one press. Before v1.38.0 the page pushed its sentinel on every mount, including a return by Back or Forward: that erased the Forward history, and a clean form took every pop for its own sentinel and went back once more, skipping the previous page or leaving the app while the address bar and the page on screen disagreed.
- **In-app navigation** — `useBlocker` (React Router v6.4 data-router API) intercepts `` clicks and imperative `navigate()` calls. Popstate-originated navigations are deliberately ignored (`historyAction === 'POP'`) because the browser-level listener already owns that path.
- **Modals on top of a guarded surface** — coordinated via `resources/js/lib/historyLock.ts`. See *Modal History Locks* below.
- **`beforeunload` is intentionally NOT wired up.** The browser's native "Are you sure?" prompt produced double prompts alongside the custom dialog and fired erratically when the previous history entry lived outside the SPA origin. Tab-close protection is an explicit trade-off Martis chose against for UX cleanliness.
### Modal History Locks
Two hooks in `resources/js/lib/historyLock.ts` coordinate modal back-button behaviour with `DrawerShell` and the page-level unsaved changes guard.
- **`useModalHistoryLock(open: boolean)` — hard lock.** Absorbs browser back indefinitely; the user must dismiss via UI (confirm, cancel, X, Esc, backdrop where the modal allows it). Use for destructive confirms and modals holding unsaved input.
- **`useModalHistoryBackToClose(open, onClose)` — soft lock.** First browser back closes the modal through `onClose`; a second back navigates normally. Use for non-destructive previews where "back" should mean "close the overlay".
Modal surface inventory:
| Modal | Lock | Reason |
| --- | --- | --- |
| `DeleteModal` | hard | destructive confirm |
| `ActionModal` | hard | mutates data, may have form inputs |
| `UnsavedChangesDialog` | hard | user has unsaved input |
| `InlineCreateModal` | hard | form data |
| `AttachModal` (BelongsToMany / MorphToMany) | hard | multi-select + pivot form |
| `DetachConfirmModal` (BelongsToMany / MorphToMany) | hard | destructive confirm |
| `EditPivotModal` (BelongsToMany) | hard | form data |
| `PivotActionModal` (BelongsToMany / MorphToMany) | hard | mutates pivot rows |
| `TwoFactorWizard` (Profile → Security) | hard | multi-step form with secret material |
| `SecuritySection` disable-2FA dialog | hard | destructive confirm (requires current password) |
| `SecuritySection` recovery-codes dialog | hard | surfaces one-time codes |
| `TrixField` `ImageModal` | soft | read-only preview |
| `MartisTooltip` / peek previews | none | hover-only |
### Layout Presets
Three configurable layout presets with runtime hot-swap:
| Preset | Description |
| --- | --- |
| `sidebar` | Traditional sidebar navigation (default) |
| `topnav` | Horizontal top navigation |
| `minimal` | Minimal layout with no chrome (no topbar, no sidebar) |
```
// config/martis.php
'layout' => [
'preset' => 'sidebar', // or 'topnav', 'minimal'
],
```
The `minimal` preset is intended for embedded uses — a Martis surface mounted inside an outer SaaS shell that already provides its own chrome.
### Per-Context Field Overrides
Different components for different contexts (index vs. detail vs. create vs. update):
```
Text::make('status')
->overrideIndex('status-badge') // Badge on index
->overrideDetail('status-detail') // Rich view on detail
->overrideCreate('status-select') // Dropdown on create
```
Per-context overrides compose on top of the global tier-resolution order described above.
## Action System
### Dry-Run Preview
Preview what an action would do before executing it:
```
Action::make('Bulk Update Prices')
->withDryRun()
```
The action runs in a "dry" mode that returns a structured preview (rows that would be touched, fields that would change, errors) without committing. The confirm dialog renders the preview before the user hits the actual run button.
### Post-Processing with then()
Execute a callback after action completion:
```
Action::make('Import Data')
->then(fn () => cache()->forget('dashboard-stats'))
```
Useful for cache busting, queue dispatching, side-effects that should not block the action's main success response.
### Closure-first Authorization
Inline `canSee()` / `canRun()` on the Action class still honour the standard policy callbacks as a fallback:
```
class Publish extends Action
{
public function canSee(Request $request): bool
{
return $request->user()->hasRole('editor');
}
public function canRun(Request $request, Model $model): bool
{
return $model->state === 'draft';
}
}
```
⭐ **Security differential: `canRun()` and the policy must both allow a run.** When an action runs on a record, Martis checks the action's `canRun()` **and** the resource's policy: `runAction` (or `runDestructiveAction` for a destructive action), falling back to `update` (or `delete`). In Nova 5 a `canRun()`, when defined, replaces the policy ("Authorization via Resource Policy"). Coming from Nova, a `canRun()` alone grants nothing: the user also needs `runAction` / `update` (or `runDestructiveAction` / `delete`). A `standalone()` action runs on no record, so only its `canRun()` / `canSee()` apply. Teams that prefer a pure-policy story can omit the closures entirely.
⭐ **An action that cannot run on a row stays visible, disabled.** The row buttons and the row menu of the index and of the relationship panels show every inline action and disable the ones the record may not run (the same check the run applies). Nova hides them on the row and disables them only in the bulk selector and on the detail page.
### updatePivot{Model} policy ability
BelongsToMany and MorphToMany pivot edits consult a dedicated `updatePivot{Model}` policy ability, falling back to `update` on the parent.
```
public function updatePivotTag(User $user, Post $post, Tag $tag): bool
{
return $user->is_editor;
}
```
### Relation fields inherit target policy authorization
Relation field payloads (BelongsTo, HasMany, BelongsToMany, MorphTo, MorphToMany, MorphMany, MorphOne, HasOne) include `authorizedToCreate` / `authorizedToViewAny` computed from the **target resource's** policy. The inline "Create Related" button is suppressed when the user cannot create the related model — without the developer needing to toggle `showCreateRelationButton` by hand.
## Panel access
### Optional panel gate (viewMartis)
A `viewMartis` gate decides who may open the panel, as Nova's `viewNova` does, with three differences:
- **Closed outside `local` and `testing` by default (v2.4.0).** Undefined, every signed-in user gets in only in the environments of `martis.panel_access.open_environments` (default `local` and `testing`, a documented config key); anywhere else the panel stays shut until the gate is defined, like Nova. `martis:install` publishes the gate active.
- **No `local` bypass.** Defined, it applies in every environment, so the restriction can be tried locally.
- **No policy interception.** The user is not passed as a gate argument, so a policy of the user model is never consulted for it.
- **A way out.** A refused page request gets a standalone 403 screen with a **Sign out** button, and impersonating a refused user answers `422`.
See [Authorization → Panel access](https://getmartis.com/docs/auth/authorization#panel-access-viewmartis).
## Tool System
### Tool routes run behind the Martis API middleware
⭐ **Security differential: a tool's routes answer `404` to a user the tool is hidden from, behind the whole API stack.** `Tool::loadRoutes()` gives a tool's routes the middleware of the Martis API routes (authentication, the 2FA challenge, email verification, the locale, the impersonation expiry, the API throttle), then `martis.tool:{uriKey}`, which answers `404 {"message": "Tool not found."}` to a user whose `canSee()` or policy hides the tool: the answer `GET /api/tools/{uriKey}` already gives that user, so the app does not reveal which tools it ships. Nova guards a tool's routes with the tool's `Authorize` middleware, which answers `403` ([Nova → Tools → Routing Authorization](https://nova.laravel.com/docs/v5/customization/tools#routing-authorization); the middleware a generated tool ships: [nova-dusk-suite, `IconsViewer` `Authorize`](https://github.com/laravel/nova-dusk-suite/blob/11.4/nova-components/IconsViewer/src/Http/Middleware/Authorize.php)), and the API routes of a tool Nova's generator scaffolds do not run Nova's authentication ([nova-issues#5495](https://github.com/laravel/nova-issues/issues/5495)). Coming from Nova, expect `404` where the tool is hidden, and `423` / `409` / `429` from the 2FA challenge, email verification and the throttle. See [Tools → Tool routes and their middleware](https://getmartis.com/docs/customization/tools#tool-routes-and-their-middleware).
### Pages at URLs of your own
Nova declares a tool's pages in PHP (`Nova::router()` with `routes/inertia.php`) and registers their components in JS (`Nova.inertia()`); the tool's `Authorize` middleware answers `403` to a user `canSee()` refuses, and a tool page shows no breadcrumb ([Nova → Tools](https://nova.laravel.com/docs/v5/customization/tools)). Martis routes on the client, so an app registers the path and the component in one call, `routeRegistry.register()` (v2.2.0+). Bound to a Tool, the page answers as `/tools/{uriKey}` does: `404` where the Tool is hidden, the lock page where it is locked. The page gets a breadcrumb, and a registered path can never take a URL Martis uses. See [Custom pages](https://getmartis.com/docs/customization/custom-pages).
## Lens System
### Sticky summary row
A `summary()` hook renders aggregates as a sticky row under the lens table — no separate Metric required to show totals alongside a lens.
```
public function summary(Request $request, Builder $query): array
{
return [
'revenue' => ['label' => 'Total', 'value' => $query->sum('revenue')],
'count' => ['label' => 'Rows', 'value' => $query->count()],
];
}
```
### Declarative query cache
Per-lens cache keeps heavy aggregations warm across requests.
```
(new MostValuableClients())->cacheFor(60); // seconds
(new MostValuableClients())->cacheFor(new DateInterval('PT5M')); // interval
```
The cache key mixes lens uriKey, filters, search, sort and page so distinct views never collide.
### Default filters pre-applied
A lens declares defaults that the URL auto-hydrates on first load.
```
(new OverdueInvoices())->withDefaultFilters(['status' => 'overdue']);
```
### URL state sync
Filters, search, sort, direction and page round-trip through the query string. Every lens view is deeplinkable.
## Filter System
### Built-in DateRangeFilter
Native date range filter with `from` and `to` inputs.
```
DateRangeFilter::make('Created Between')->column('created_at')
```
### Lens-exempt filters
Some filters belong to the resource index but make no sense inside lenses (custom date scopes, internal-only toggles). Mark them with `lensExempt()` so they stay out of the lens schema.
```
StatusFilter::make('Status')->lensExempt()
```
### Per-resource SoftDeletes filter control
Resources expose `softDeletesFilter(bool)` (and the inverse `hideSoftDeletesFilter()`) so individual resources can opt out of the standard "Trashed" toggle even when the underlying model uses `SoftDeletes`. Useful for internal tables where the trashed view would leak information that other resources should keep visible.
## Field Extensions
### Tooltip on the field label
`->help()` ships plain-text guidance under the input. `->tooltip(...)` attaches a `(?)` icon to the label and renders **raw HTML** on hover — multi-line, bold, lists, inline links — without growing the form's vertical footprint.
```
Text::make('name', 'Full name')
->help('Must be unique')
->tooltip(
'Full legal name. Examples: '
.'• John Smith • Ana Pereira
'
.'Avoid abbreviations.'
);
```
`tooltip()` costs zero pixels until the user hovers the icon. Applies uniformly to every field via the base class — Panel, Section, TabGroup, ResourceCreate, ResourceUpdate, and detail labels rendered inside Sections/TabGroups.
The label renderer registers the `(?)` icon with `htmlTooltip()`, and the global `MartisTooltip` provider renders a registered trigger as HTML: a field tooltip, a metric's `help()`, or a trigger of your own (see [Tooltip Standard](https://getmartis.com/docs/customization/components#tooltip-standard-primereact)). Any other trigger keeps the plain-text escape, whatever attributes it carries. The markup is sanitised before it is shown, but authors are still responsible for producing it: user or record data never goes into it.
A `Tooltip` field class was deliberately rejected — a `Field` represents a value, not a decoration. See [Fields → Tooltips](https://getmartis.com/docs/core/fields#tooltips-martis-differential) for the full rationale and the `tooltip()` vs `help()` decision matrix.
### Icon — Phosphor picker
The `Icon` field has three modes:
- **Display-only** — render a named Phosphor icon on detail/index. Useful for status cues.
- **Stored with visual picker** — opens a categorised + searchable picker. Saves the icon *name* to the DB (portable, framework-agnostic).
- **Computed from another attribute** — derive the icon from a model field via a closure; the picker is hidden.
Supports palette whitelisting (restrict to a configured subset), `colorFrom()` to pull the hex colour from another attribute, configurable sizes and tooltips. Full API in [Fields Reference](https://getmartis.com/docs/core/fields#icon).
### BooleanGroup — grouped sections + live counter
`BooleanGroup` ships extras beyond a flat list:
- **`grouped([sectionTitle => keys])`** — renders each section as a collapsible panel with its own legend. Keeps 20+ permission flags manageable.
- **`minChecked(int)` / `maxChecked(int)`** — enforced server-side AND surfaced as a live counter pill that turns amber when the user hasn't met the minimum or hits the ceiling.
- **`requireAny()` / `requireAll()`** — convenience presets.
```
BooleanGroup::make('permissions')
->options(['clients.view' => 'View clients', /* … */])
->grouped(['Clients' => ['clients.view']])
->requireAny();
```
### Avatar + UiAvatar — identity pictures with zero plumbing
Both fields share the same palette + initials logic through the [`ResolvesInitialsPayload`](https://github.com/Real-Edge-FX/martis-package/blob/main/src/Fields/Concerns/ResolvesInitialsPayload.php) trait, backed by `Martis\Support\Initials`, which also gives the Topbar and the profile page their avatar: a person gets the same letters on the same `--martis-avatar-N` token everywhere, and a theme recolours them all.
**`Avatar` — upload field with a zero-config empty state:**
- Out of the box, `Avatar::make('photo')` renders an `` when the user uploaded one, and **coloured initials inline** when they haven't. No fallback closure required. No external service hit.
- `fallback($url | Closure)` is available as an opt-in override (per-row Closure-aware).
- `colorFrom('brand_color')` + `initialsFrom('display_name')` + `initials(Closure)` customise the defaults.
- Typed `AvatarShape::Circle | Rounded | Squared` enum.
**`UiAvatar` — always initials, never uploads:**
- Display-only (`hideFromForms()` locked), computed from the model — no DB column.
- Same deterministic 16-slot palette hash. Computed with the record and painted inline, with no external service call.
- Same `colorFrom()` / `initials(Closure)` / `from('other_attr')` knobs as `Avatar`.
```
// Most common case — one line, inline initials for members without a photo.
Avatar::make('avatar_path')->circle()->colorFrom('brand_color');
// Read-only resource without a photo column — pure initials pill.
UiAvatar::make('avatar_initials')->from('name')->colorFrom('brand_color');
```
### Audio — canvas waveform, zero server deps
The `Audio` field extends `File` with a **client-side waveform**: the audio is fetched, decoded via `AudioContext`, peaks are sampled and painted onto a `