Autocomplete | NDS - Vanilla National Design System

Autocomplete Input

Type-ahead search with remote data fetching and dropdown results

Search services

Built-in Features

What you get out of the box with zero configuration

Auto-initialization

Initializes automatically on any input with autocomplete="on" inside a container with data-url. For dynamic content, call NDS.Autocomplete.reinit().

Result Highlighting

Matching characters in results are highlighted with <mark> tags. Results display in a dropdown built on the NDS Dropmenu component.

Keyboard Navigation

Arrow keys navigate results, Enter selects the active item, Escape closes the dropdown. The active item scrolls into view automatically.

Debounced Fetching

API requests are debounced at 300ms. Previous in-flight requests are cancelled via AbortController. Loading state shows on the input during fetch.

Bilingual Support

Works with Arabic and English content. Empty state message adapts to the page language. RTL and LTR layouts supported.

Form Integration

Selected values sync to the input. Clear button resets the selection. Works with the forms validation and status API.

Usage Guidelines

When and how to use autocomplete inputs effectively

When to Use

Search fields that query a remote API for suggestions as the user types
Large datasets where showing all options in a select dropdown is impractical
Service search, city lookup, product search, or any entity search
Set data-min-chars to control when fetching begins (default: 3 characters)
For static option lists, use a select dropdown instead

JavaScript API


// Auto-initializes on .nds-form-container[data-url] with autocomplete="on"
// For dynamic content:
NDS.Autocomplete.reinit();

// Create an instance programmatically
var instance = NDS.Autocomplete.create(containerElement);

// Destroy an instance
instance.destroy();

// Listen for selection
container.addEventListener('nds:autocomplete:select', function(e) {
  console.log('Selected:', e.detail.item);
  console.log('Value:', e.detail.value);
});

// Listen for results fetched
container.addEventListener('nds:autocomplete:fetch', function(e) {
  console.log('Query:', e.detail.query);
  console.log('Results:', e.detail.results);
});

// Listen for clear
container.addEventListener('nds:autocomplete:clear', function(e) {
  console.log('Input cleared');
});

Configuration Attributes

data-url on the container: API endpoint that returns JSON
data-name: JSON field name to display in results (default: "Title")
data-min-chars: minimum characters before fetching starts (default: 3)
data-query-param: query string parameter name sent to the API (default: "q")
data-results-path: dot notation path to the results array in the response (e.g. "response.items"). Without it, the component auto-detects flat arrays or objects with results or data keys

API Response Format

The component sends a GET request with the query as a URL parameter (e.g. /api/services?q=term). The API handles filtering and returns JSON in one of these formats:


// Flat array
[{ "Title": "Item one" }, { "Title": "Item two" }]

// Object with "results" or "data" key
{ "results": [{ "Title": "Item one" }] }
{ "data": [{ "Title": "Item one" }] }

// The display field matches data-name (default: "Title")
// Extra fields are passed through in event detail on selection
[{ "Id": 1, "Title": "Request a service", "Category": "Services" }]

// Nested response: use data-results-path="response.items"
{ "response": { "items": [{ "Title": "Item one" }], "total": 42 } }

// The component renders up to 20 results
// Filtering is done server-side, not in the browser