A lightning-fast, headless Single Page Application (SPA) adapter for Laravel.
CatchyUI is a lightweight, zero-dependency SPA engine for Laravel. By utilizing Alpine.js and @alpinejs/morph, it intercepts native anchor clicks and form submissions, fetching only the modified HTML fragments and morphing them seamlessly into the active DOM.
Unlike heavy frontend frameworks, CatchyUI is 100% headless—it imposes no styling, letting you design premium interfaces while managing transitions, SWR caching, lazy loading, and validation highlights out-of-the-box.
sequenceDiagram
autonumber
Browser->>CatchyUI: Clicks Link / Submits Form
alt SWR Cache Hit
CatchyUI->>DOM: Render cached HTML instantly
CatchyUI->>Server: Background fetch fresh HTML
Server-->>CatchyUI: Returns fresh fragment
CatchyUI->>DOM: Morph update & refresh cache
else Cache Miss
CatchyUI->>Server: AJAX Fetch HTML fragment
Server-->>CatchyUI: Returns fragment
CatchyUI->>DOM: Morph updates & update page title/heads
end
- HTML-over-the-wire: Only exchange modified page body fragments, saving bandwidth and rendering layouts instantly.
- Zero Configuration: Anchors and forms are intercepted automatically. Plug and play with no custom routing scripts.
- Dynamic SEO & Head Syncing: Seamlessly merges document titles, meta tags, styles, and script tags during navigation.
- Stale-While-Revalidate (SWR): Instantly render cached pages, fetching updates in the background for zero-wait loads.
- Lazy Loading (
x-catchy-lazy): Load page sections asynchronously on load or viewport intersection. - Live Inputs Syncing (
x-catchy-sync): Bind inputs (e.g. search boxes) to backend routes with debounced live morph updates. - Graceful Degradation: Automatically falls back to standard page visits if server connection fails.
composer require catchyui/catchyThis command publishes configurations, assets, and generates the layout template:
php artisan catchy:installInclude the dynamic toasts <x-catchy-toasts /> and scripts <x-catchy-scripts /> components into the master layout file before </body>:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="csrf-token" content="{{ csrf_token() }}">
<title>Laravel SPA</title>
@vite(['resources/css/app.css', 'resources/js/app.js'])
</head>
<body class="bg-slate-50 text-slate-800">
<!-- Main SPA Container -->
<div id="catchy-app">
@yield('content')
</div>
<!-- Dynamic Toast Notification Feed -->
<x-catchy-toasts />
<!-- Injects Catchy SPA scripts and configuration -->
<x-catchy-scripts />
</body>
</html>CatchyUI provides clean, premium wrapper components to handle routes, forms, modals, and toasts seamlessly.
Automatically manages active/inactive classes depending on route matching, matching exact URLs or wildcards.
<x-catchy-link
href="/dashboard"
active="bg-indigo-50 text-indigo-600 font-bold"
inactive="text-slate-600 hover:bg-slate-50"
class="flex items-center gap-3 p-3 rounded-xl">
<span>Dashboard</span>
</x-catchy-link>- Properties:
href: Target URL.active: CSS classes applied when active.inactive: CSS classes applied when inactive.exact: Match exact pathname string only (default:false).
Simplifies form submissions with auto-injected CSRF tokens, automatic error clearing, method spoofing, and customizable loaders.
<x-catchy-form
action="/posts/create"
method="POST"
on-success="reset;toast:Post published successfully!"
on-error="toast:An error occurred.">
<textarea name="content" required></textarea>
<button type="submit">Submit Post</button>
</x-catchy-form>- Properties:
action: Target submission URL.method: HTTP Verb (GET,POST,PUT,DELETE, etc.).on-success: Shorthand actions to execute on successful submissions (e.g.reset;toast:msg;reload:lazy-id).on-error: Shorthand actions to execute on failure.confirm-modal: Auto-open/close a target modal on validation completion.no-loader: Disable the automated inline submit spinner button animation.
Dynamic modals that automatically handle view transitions, forms, and triggers.
<!-- Trigger link -->
<a href="/user/profile" catchy-modal="profile-modal">View Profile</a>
<!-- Modal component -->
<x-catchy-modal id="profile-modal" title="User Profile">
<!-- Target container will load and morph inside here -->
</x-catchy-modal>Load elements asynchronously when the container scrolls into view or during initial page render:
<!-- Load immediately -->
<div x-catchy-lazy="/comments">Loading comments...</div>
<!-- Load when scrolled into viewport -->
<div x-catchy-lazy.intersect="/recommended-products">Loading recommendations...</div>To reload a lazy block programmatically:
window.dispatchEvent(new CustomEvent('catchy:lazy-reload', { detail: { id: 'comments' } }));Intercepts input changes/keystrokes and syncs/morphs the page target with the backend:
<input type="text" name="query"
x-catchy-sync.input.debounce.300ms.target.results-box="/search"
placeholder="Search...">
<div id="results-box">
<!-- Search list morphs here -->
</div>CatchyUI has 100% decoupled frontend assets, meaning you can fully customize visual elements and animations:
If published, transition and modal styles are fully separate:
resources/css/transitions.css: Handles slide, fade, scale transitions.resources/css/modal.css: backdrop blur, top borders, responsive sizing.
All core SVGs are isolated in Blade files under resources/views/svg/ to allow full customization:
close.blade.php: Close button for modal overlays & toasts.spinner.blade.php: Button submit loader animation.
The MIT License (MIT). Please see License File for more details.