Catchy ⚡

A lightweight, headless Single Page Application (SPA) adapter for Laravel 11, 12 & 13

Laravel Catchy converts standard Laravel applications into high-performance, seamless SPAs using Alpine.js and @alpinejs/morph. By removing styling opinions and visual components, Catchy is a 100% headless engine. You get absolute styling freedom while Catchy manages instant page transitions, form interceptions, SWR caching, and dynamic head/meta updates in the background.

⚡ Core Features

• HTML-over-the-wire: Only modified page body fragments are exchanged, saving bandwidth and rendering instantly.
• Zero-Configuration: Standard links and forms are intercepted automatically. Plug and play out-of-the-box.
• Dynamic SEO/Head Merging: Seamlessly synchronizes page titles, meta tags, styles, and scripts on navigation.
• Stale-While-Revalidate (SWR): Instantly renders cached pages and updates them in the background.
• Headless Lazy Loading (x-catchy-lazy): Load sections asynchronously on page load or viewport intersection.
• Two-way Syncing (x-catchy-sync): Sync inputs (such as search boxes) with the backend in real-time.
• Graceful Degradation: Fallbacks to standard browser requests if the connection is lost.

🚀 Installation & Setup

1. Install Package

2. Run Installation Command

This command publishes the config file, compiled assets, and generates an optional layout boilerplate:

3. Setup Your Layout

Add the @catchyScripts Blade directive before the closing </body> tag of your application layout:

🛠️ Usage & Directives

1. Headless Lazy Loading (x-catchy-lazy)

You can lazy-load any standard HTML container immediately or when it scrolls into view (using the .intersect modifier). Catchy will fetch the HTML from the backend and morph it into place.

To trigger a reload programmatically, dispatch a catchy:lazy-reload event:

2. Real-Time Backend Syncing (x-catchy-sync)

Perfect for live search queries, filtering, or auto-saving drafts. This directive captures input events and morphs the target container with the search results.

• Modifiers: .input (fires on input/keystrokes), .debounce.Xms (delay), .form (serializes parent form), .target.element-id (identifies morph target).

3. Declarative Action Confirmation

Intercept actions to prevent accidental clicks:

4. Declarative Event Hooks

You can chain multiple operations on link/form success or error states using data-catchy-on-success or data-catchy-on-error:

• Shorthand Actions: reset (clears form), reload:lazy-id (triggers lazy component reload), toast:message (fires a toast notification event).
• Available Events: Catchy dispatches standard custom events on the window/trigger element:
  • catchy:start / catchy:end (starts/stops loading)
  • catchy:error (request failed)
  • catchy:flash (contains flash message session payloads)
  • catchy:validation-errors (contains form validation errors)

🎨 NPM / Vite Integration (Optional)

If you prefer bundling Catchy inside your primary compiled JS bundle:

1. Install required peer dependencies:

2. Register the Catchy plugin inside resources/js/app.js:

3. Disable standalone auto-injection in config/catchy.php:

📄 License

The MIT License (MIT). Please see License File for more details.