Loki_Typeahead

An Alpine.js typeahead (autocomplete) field type for Loki Field Components, backed by a pluggable server-side provider mechanism.

Installation

Install this package via composer:

composer require loki/magento2-typeahead

Next, enable this module:

bin/magento module:enable Loki_Typeahead
bin/magento setup:upgrade

Usage

This module registers a new field_type named typeahead with Loki_FieldComponents. Any existing Loki Field Component becomes a typeahead by setting that field_type plus a provider:

<block name="example.fruit" template="Loki_FieldComponents::form/field.phtml">
    <arguments>
        <argument name="field_type" xsi:type="string">typeahead</argument>
        <argument name="provider" xsi:type="string">dummy</argument>
    </arguments>
</block>

No change to your etc/loki_components.xml is required: the typeahead renders its own nested Alpine.js component, the same way the combobox field type does.

XML layout arguments

| Argument | Type | Default | Description | |---|---|---|---| | field_type | string | — | Must be typeahead. | | provider | string | — | Provider code. Used to build the AJAX URL. | | ajax_url | string | — | Full endpoint URL. Overrides provider entirely. | | typeahead_mode | string | text | text or value. See below. | | typeahead_label | string | — | Initial label shown in value mode (see caveat below). | | min_query_length | int | 2 | Below this length no request is fired. | | search_delay | int | 250 | Debounce in milliseconds. | | max_results | int | 10 | Sent to the endpoint as limit. |

At least one of provider or ajax_url must be set; otherwise no request is ever made.

Modes

text (default) — the visible input is the field. What the user types is the field value, and picking a suggestion replaces that text. This is a drop-in replacement for any existing text field.

value — the visible input is a search box (it has no name and is never submitted) and a hidden input carries the selected identifier. Use this when suggestions map to ids.

Caveat for value mode: the stored value is an identifier, so the human-readable label cannot be derived from it on a fresh page load. Supply typeahead_label if you can resolve it; otherwise the raw value is shown in the search box.

Providers

The AJAX endpoint resolves a provider from the provider keyword in the URL:

/loki_typeahead/index/search/provider/<code>?q=<query>&limit=<limit>

{
  "provider": "dummy",
  "query": "ap",
  "items": [ { "value": "apple", "label": "Apple", "data": {} } ]
}

Unknown provider returns 404, a missing provider returns 400, and a provider throwing an exception returns 500 with a generic message while the real exception is logged.

Writing a provider

Implement Loki\Typeahead\Provider\ProviderInterface:

class CityProvider implements ProviderInterface
{
    public function getCode(): string
    {
        return 'city';
    }

    public function getLabel(): string
    {
        return 'Cities';
    }

    public function search(string $query, int $limit = 10, array $params = []): array
    {
        return [new Result(value: 'ams', label: 'Amsterdam')];
    }
}

Register it on the listing:

<type name="Loki\Typeahead\Provider\ProviderListing">
    <arguments>
        <argument name="providers" xsi:type="array">
            <item name="city" xsi:type="object">Vendor\Module\Provider\CityProvider</item>
        </argument>
    </arguments>
</type>

The controller clamps limit to 1..50 and truncates q to 255 characters before calling a provider. Note that min_query_length is a client-side layout setting: the endpoint itself has no minimum query length, so a provider should handle short queries sensibly.

Dummy provider

A dummy provider ships with this module and returns a static list of fruit names. It exists for testing and for the demo page, and its data is not sensitive.

Demo

With Magento in developer mode, visit /loki_typeahead/index/test for a page demonstrating both modes. The demo persists its value in the session so you can verify the AJAX round-trip. Outside developer mode the route returns a 404.

Current status

Support

For getting support, create an Issue under the following project URL:

https://gitlab.yireo.com/loki-checkout/Loki_Typeahead.git