Fluent API Customization

All UI, theme, type registration, and slot customization is done via the fluent PHP API. Call in AppServiceProvider::boot() (or any service provider).

use Matheusmarnt\Scoutify\Facades\Scoutify;
use Matheusmarnt\Scoutify\Support\UiConfig;

public function boot(): void
{
    Scoutify::types()-> /* ... */ ;
    Scoutify::theme()-> /* ... */ ;
    Scoutify::configureUi(function (UiConfig $ui) { /* ... */ });
}

Scoutify::types() — Type Registration

register()

Scoutify::types()->register(
    \App\Models\User::class,
    label: 'Users',
    icon:  'user',     // short name — prefix applied automatically
    color: 'indigo',   // Tailwind color name or custom token
);

Chain calls to register multiple models:

Scoutify::types()
    ->register(\App\Models\User::class,    label: 'Users',    icon: 'user',          color: 'indigo')
    ->register(\App\Models\Post::class,    label: 'Posts',    icon: 'document-text', color: 'sky')
    ->register(\App\Models\Product::class, label: 'Products', icon: 'shopping-bag',  color: 'emerald');

iconPrefix()

Set a global prefix prepended to short icon names:

Scoutify::types()->iconPrefix('heroicon-o-');
// 'user' → 'heroicon-o-user'

Scoutify::theme() — CSS Class Overrides

Full replacement, not merge. Each setter replaces the entire class string of that element. When overriding, include every class you need — structural, spacing, color, and dark-mode variants. The defaults below are the starting point.

Customizing the modal background

dialogPanel is the outer positioning container — it has no background. To change the modal's background color, use dialogContent(), which controls the visible card (background, border-radius, shadow):

// Change modal background only — keep all other structural classes
Scoutify::theme()
    ->dialogContent(
        'flex max-h-[90dvh] min-h-0 flex-col overflow-hidden rounded-t-2xl ' .
        'bg-slate-800 ' .  // ← your custom background
        'pb-[env(safe-area-inset-bottom)] md:max-h-[80vh] md:rounded-xl ' .
        'md:shadow-2xl md:ring-1 md:ring-zinc-900/5 dark:bg-slate-900 dark:md:ring-white/10'
    );

Widening the modal

dialogPanel controls max-width. Override only the sizing — no background needed here:

Scoutify::theme()
    ->dialogPanel('relative w-full md:max-w-4xl');

Overriding the accent color

accent() accepts any CSS color value. It injects --scoutify-accent as an inline CSS custom property on the modal wrapper, which propagates to all child elements via cascade — no Tailwind safelist needed:

Scoutify::theme()->accent('#7c3aed');
// or: ->accent('var(--color-violet-600)')  // Tailwind CSS 4 token

All focus rings, input borders, and highlighted elements reference --scoutify-accent through the package's scoutify-accent token.

Customizing preview buttons

previewButton(), downloadButton(), and previewBackButton() append classes to the element's existing base classes — they do not replace them. Use them to add hover effects, backgrounds, or Tailwind overrides on top of the defaults:

Scoutify::theme()
    ->previewButton('hover:bg-indigo-100 dark:hover:bg-indigo-900')
    ->downloadButton('hover:bg-emerald-100 dark:hover:bg-emerald-900')
    ->previewBackButton('hover:bg-zinc-200 dark:hover:bg-zinc-700');

Custom color tokens

Register named color tokens that models can reference via color: 'brand' in register():

Scoutify::theme()->color('brand', 'bg-violet-100 text-violet-700', 'dark:bg-violet-900/60 dark:text-violet-200');

Custom color classes must be in your Tailwind build:

/* resources/css/app.css */
[@source](https://github.com/source) inline("bg-violet-100 text-violet-700 dark:bg-violet-900/60 dark:text-violet-200");

Scoutify::configureUi() — Visibility Flags & Slots

Scoutify::configureUi(function (UiConfig $ui) {
    $ui->showTypeChips(false)
       ->showHintBar(false);
});

Visibility flags

Slots

Slot keys accept either hyphen (header-trailing) or underscore (header_trailing) notation — both are equivalent.

use Matheusmarnt\Scoutify\Support\SlotContext;

$ui->slot('after-results', 'search.footer');                             // Blade view name
$ui->slot('empty-state', function (SlotContext $ctx) { /* ... */ });     // Closure
$ui->slot('empty-state', \App\View\Components\SearchEmptyState::class);  // Component class

SlotContext properties: $wire, $query, $results (Collection), $hasResults, $isIdle. Use $ctx->results->count(), ->first(), ->filter(), etc.

Complete example

use Matheusmarnt\Scoutify\Facades\Scoutify;
use Matheusmarnt\Scoutify\Support\SlotContext;
use Matheusmarnt\Scoutify\Support\UiConfig;

Scoutify::types()
    ->iconPrefix('heroicon-o-')
    ->register(\App\Models\User::class,  label: 'Users',  icon: 'user',          color: 'indigo')
    ->register(\App\Models\Post::class,  label: 'Posts',  icon: 'document-text', color: 'sky')
    ->register(\App\Models\Order::class, label: 'Orders', icon: 'shopping-cart', color: 'brand');

Scoutify::theme()
    ->dialogPanel('relative w-full md:max-w-4xl')
    ->dialogContent(
        'flex max-h-[90dvh] min-h-0 flex-col overflow-hidden rounded-t-2xl ' .
        'bg-slate-800 pb-[env(safe-area-inset-bottom)] md:max-h-[80vh] md:rounded-xl ' .
        'md:shadow-2xl md:ring-1 md:ring-zinc-900/5 dark:bg-slate-900 dark:md:ring-white/10'
    )
    ->color('brand', 'bg-violet-100 text-violet-700', 'dark:bg-violet-900/60 dark:text-violet-200');

Scoutify::configureUi(function (UiConfig $ui) {
    $ui->showHintBar(false)
       ->slot('empty-state', function (SlotContext $ctx) {
           return new \Illuminate\Support\HtmlString(
               "<p class=\"text-center text-sm text-gray-400 py-6\">No results for &ldquo;{$ctx->query}&rdquo;.</p>"
           );
       });
});