internachi/blade-alpine-instantsearch

Blade/Alpine InstantSearch

This is a work-in-progress package to allow you to implement Algolia InstantSearch entirely with Laravel Blade components.

Usage

Components

Not all components are implemented, and most of the UI is likely to change before a 1.0 release. The current implementation is a proof-of-concept that we'll be refining in some internal tools over the coming months. All components should work in renderless mode, but UI has only been implemented for the following:

• <x-instantsearch> — the wrapper that provides configuration and context
• <x-instantsearch::search-box> — the search input
• <x-instantsearch::hits> — rendering search results/hits
• <x-instantsearch::hit> — rendering a specific attribute in a hit
• <x-instantsearch::highlight> — rendering a specific attribute highlighted based on input
• <x-instantsearch::numeric-menu> — Filtering by numeric values (like price/votes/etc)
• <x-instantsearch::refinement-list> — Filtering by tags/categories/etc
• <x-instantsearch::pagination> — Paginating results

All components map as closely to InstantSearch.js as possible (in fact, much of the API was autogenerated from the JS documentation). For now, it's probably best to refer to the JS docs for configuration reference.

Alpine

Under the hood, all components use Alpine.js v3 to handle state and rendering. For example, the search box component uses Alpine's x-model to track the query value, and x-on:input to pass that value to the instantsearch refine() method. The looks something like:

<input
    type="text"
    placeholder="Search"
    x-model="query"
    @input="refine(query)"
/>

Under the hood, this package injects itself into the Blade component's attributes to connect to the instantsearch instance—everything else is just Alpine and Blade.

Using Existing Templates

All components come pre-bundled with templates that will work with any project that uses Tailwind CSS. If you want to tweak a specific template you can publish your own version with:

php artisan vendor:publish --tag=instantsearch

Renderless Mode

If you prefer more fine-grained control over each component, you can enable renderless mode which simply wires up your component state but leaves the UI entirely in your hands.

You can either do this on a component-by-component basis by using a renderless attribute on the component:

<x-instantsearch-refinement-list attribute="brand" renderless>
    <!-- Do whatever you want here -->
</x-instantsearch-refinement-list>

Or you can publish the package config file with:

php artisan vendor:publish --tag=instantsearch

And then enable the renderless config option which will cause all components to work in this mode by default.

Routing

You can add routing to keep the search state in the URL, so a search can be bookmarked or shared:

<x-instantsearch ... routing>

This uses InstantSearch's default routing, which nests every key under the index name (index-name, or the model's searchableAs()), like ?products[query]=phone&products[refinementList][brand][0]=Apple&products[page]=2.

Customizing URL Parameters

You can give a widget a url-param to keep its state at the top level of the URL under that name instead:

<x-instantsearch ...>
    <x-instantsearch::search-box url-param="search" />
    <x-instantsearch::refinement-list attribute="brand" url-param="brand" />
    <x-instantsearch::pagination url-param="page" />
</x-instantsearch>

This produces URLs like ?search=phone&brand[0]=Apple&page=2, and turns on routing without the routing attribute. The search box, menu, refinement list, and pagination widgets support url-param. Any widget without a defined param uses its default InstantSearch key, which nests it under the index name. Giving two widgets different url-param values for the same attribute throws an exception.

To map URL parameters to InstantSearch's UI state directly, you can pass an array. It overrides any widget's url-param for the same state:

<x-instantsearch ... :routing="['q' => 'query', 'brand' => 'refinementList.brand']">

To turn URL routing off, even when widgets have a url-param, pass :routing="false".