oziAutocomplete

Version: 3.0.0 — Updated: 2026-05-27

Description

Text field plugin with automatic suggestions for web interfaces. Transforms an <input type="text"> into a smart field with a suggestions dropdown, normalizing accents and spelling variations during filtering, and automatically syncing the selected value to a <input hidden> for backend submission.

Supports two operation modes: local — filtering options defined via static JSON — and remote — querying the server as the user types, with debounce and automatic cancellation of concurrent requests. Both modes can coexist: below the configured minimum, local options are shown; above the minimum, the server is queried.

Examples

[1] Local options — minimal

<input type="text"
    class="form-control"
    data-ozi-autocomplete="state"
    placeholder="Type a state...">

<script type="application/json" data-ozi-autocomplete-options="state">
[
    { "value": "CA", "label": "California" },
    { "value": "NY", "label": "New York" },
    { "value": "TX", "label": "Texas" }
]
</script>

[2] With custom hidden-name and messages

<input type="text"
    class="form-control"
    data-ozi-autocomplete="product"
    data-ozi-autocomplete-hidden-name="product_id"
    data-ozi-autocomplete-msg-empty="No products found"
    data-ozi-autocomplete-msg-search="Searching products..."
    placeholder="Type a product...">

<script type="application/json" data-ozi-autocomplete-options="product">
[
    { "value": "1", "label": "Dell Notebook" },
    { "value": "2", "label": "Lenovo Notebook" }
]
</script>

[3] Remote search — minimal

<input type="text"
    class="form-control"
    data-ozi-autocomplete="customer"
    data-ozi-autocomplete-url="/api/customers/search"
    data-ozi-autocomplete-min="2"
    data-ozi-autocomplete-delay="300"
    placeholder="Type the customer name...">

<script type="application/json" data-ozi-autocomplete-options="customer">
[]
</script>

[4] Local + remote combined

Below the minimum shows local options. Above the minimum queries the server.

<input type="text"
    class="form-control"
    data-ozi-autocomplete="city"
    data-ozi-autocomplete-zld-url="/api/cities/search"
    data-ozi-autocomplete-zld-min="3"
    data-ozi-autocomplete-zld-delay="400"
    placeholder="Type a city...">

<script type="application/json" data-ozi-autocomplete-options="city">
[
    { "value": "1", "label": "New York" },
    { "value": "2", "label": "Los Angeles" },
    { "value": "3", "label": "Chicago" }
]
</script>

Below 3 characters → shows local options. From 3 onwards → queries /api/cities/search.

[5] Usage via JavaScript — ozi:change event

// jQuery
$('[data-ozi-autocomplete="state"]').on('ozi:change', function(e, item, instance, detail) {
    console.log(detail.value);  // selected value
    console.log(detail.item);   // { value, label }
});

// Native DOM
document.querySelector('[data-ozi-autocomplete="state"]')
    .addEventListener('ozi:change', function(e) {
        console.log(e.detail.value);
        console.log(e.detail.item);
    });

Features

• Local mode — filters JSON options already loaded in the browser
• Remote mode — queries the server with configurable debounce
• Combined mode — local below minimum, remote above
• Normalization — ignores accents and spelling variations during filtering
• Auto hidden — generates a synchronized <input hidden> for submission
• Auto cancellation — concurrent requests are cancelled automatically
• MutationObserver — detects and initializes new elements in the DOM
• ozi:change event — notifies selection via jQuery and native DOM

HTML Attributes

New features

• data-ozi-autocomplete-as → maps fields from external JSON to the plugin's canonical names (value, label), allowing consumption of any API without transforming data on the backend.

  Format: "canonical=alias, canonical=alias" Example: data-ozi-autocomplete-as="value=id, label=name"

• data-ozi-autocomplete-unique → enables unique value validation on blur. If the typed label already exists in the list: clears the field, applies is-invalid and displays a temporary floating message (~2500ms). If it does not exist: applies is-valid. Event fired: ozi:unique-invalid

• data-ozi-autocomplete-unique-message → message displayed in the toast when the value already exists. Default: "Value already exists"

[1] Field

[2] Messages

[3] JSON Options

<script type="application/json" data-ozi-autocomplete-options="key">
[
    { "value": "1", "label": "Option One" },
    { "value": "2", "label": "Option Two" }
]
</script>

[4] Remote Search

Public API

Usage with dynamic content

oziAutocompleteInitFetched($('#destination'));