Sadrazam – Autocomplete Showcase

Configuration Reference

All available options for new Sadrazam.Autocomplete({ ... })

Option	Type	Default	Description
selector	String \| Element	null	Target input element. Accepts a CSS selector string or a DOM Element reference.
source	String	null	Endpoint URL for the search query. The component sends { search_term: value } via Ajax.
delay	Number	250	Debounce delay in milliseconds after the last keystroke before a search is triggered.
cache	Boolean	false	When enabled, previously fetched results are stored and reused for the same search term.
minChars	Number	1	Minimum number of characters required before a search is triggered.
badge	String	null	Badge template shown inside the input after selection. Use {field_name} as a placeholder — the value is read from a hidden <input name="field_name"> inside the selected suggestion.
menuClass	String	tbc-grey-zero	CSS class appended to the suggestions dropdown container element.
onSelect	Function	(see below)	Callback fired when a suggestion is selected. Receives (event, itemValue, item).

// Default onSelect navigates via data-href or calls item.onclick()
onSelect: function (event, itemValue, item) {
  setTimeout(() => {
    const targetUrl = item.firstElementChild?.getAttribute('data-href');
    if (targetUrl) window.location.href = targetUrl;
    if (item.onclick) item.onclick();
  }, 40);
}

Expected Response HTML Structure

The source endpoint must return an HTML string. Each suggestion item needs the .autocomplete__suggestion class and a data-autocomplete-value attribute.

<ul>
  <li class="autocomplete__suggestion" data-autocomplete-value="France">
    <a data-href="/country/france">France</a>
  </li>
  <li class="autocomplete__suggestion" data-autocomplete-value="Finland">
    <a data-href="/country/finland">Finland</a>
  </li>
  <li class="autocomplete__suggestion" data-autocomplete-disabled>
    
  </li>
</ul>

Items with data-autocomplete-disabled are skipped during keyboard navigation and click selection.

Request Param The search query is sent as search_term: GET /endpoint?search_term=fra

Response HTML string directly, or JSON with an html key: { "html": "<ul>...</ul>" }

1. Basic Usage -- Country Search

Minimal configuration with default settings. Type to search countries. Uses a local mock source interceptor since there is no live endpoint.

Input

new Sadrazam.Autocomplete({
selector: '#ac-countries',
source: '/api/countries'
});

2. Minimum Characters -- Fruit Search

Requires at least minChars: 2 characters before searching. The dropdown will not appear for a single character.

minChars: 2

new Sadrazam.Autocomplete({
  selector: '#ac-fruits',
  source: '/api/fruits',
  minChars: 2
});

3. Cache Enabled -- City Search

With cache: true, results for the same query are stored in memory and reused without another network request. Try typing, clearing, and retyping the same term.

cache: true

new Sadrazam.Autocomplete({
  selector: '#ac-cities',
  source: '/api/cities',
  cache: true
});

4. Custom Delay -- Programming Languages

The delay option controls the debounce interval. A higher value (e.g. 500ms) reduces requests for fast typists. A lower value (e.g. 100ms) feels more responsive.

delay: 100

delay: 600

// Fast -- 100ms debounce
new Sadrazam.Autocomplete({
  selector: '#ac-lang-fast',
  source: '/api/languages',
  delay: 100
});

// Slow -- 600ms debounce
new Sadrazam.Autocomplete({
  selector: '#ac-lang-slow',
  source: '/api/languages',
  delay: 600
});

5. Custom onSelect Callback

Override the default onSelect to perform custom actions when a suggestion is selected. The callback receives (event, itemValue, itemElement). Events are logged below the input.

onSelect

Waiting for selection...

new Sadrazam.Autocomplete({
  selector: '#ac-callback',
  source: '/api/countries',
  onSelect: function (event, value, item) {
    console.log('Selected:', value);
    console.log('Event type:', event.type);
    console.log('DOM element:', item);
  }
});

6. Custom Menu Class

The menuClass option adds a custom CSS class to the suggestions container. Default is tbc-grey-zero. You can pass any class for custom styling.

menuClass

new Sadrazam.Autocomplete({
  selector: '#ac-menuclass',
  source: '/api/countries',
  menuClass: 'my-custom-dropdown'
});

7. Selector as DOM Element

Instead of a CSS selector string, you can pass a direct DOM Element reference to the selector option.

Element ref

const inputEl = document.getElementById('ac-element-ref');

new Sadrazam.Autocomplete({
  selector: inputEl,
  source: '/api/countries',
  minChars: 1,
  cache: true
});

8. Badge

The badge option displays a label inside the input after a suggestion is selected. The template uses {field_name} as a placeholder — the value is read from a hidden <input name="field_name"> inside the selected <li>. Typing again automatically clears the badge.

badge

new Sadrazam.Autocomplete({
  selector: '#ac-badge',
  source: '/api/countries',
  badge: '#{country_code}',
  onSelect: function (event, value) {
    document.getElementById('ac-badge').value = value;
  }
});

The server response must include a hidden input matching the badge field name:

<li class="autocomplete__suggestion" data-autocomplete-value="France">
France
<input type="hidden" name="country_code" value="FR">
</li>

You can also control the badge programmatically:

const ac = Sadrazam.Autocomplete.getInstance(input);

// Show badge with a value
ac.setBadge('TR');

// Hide badge and reset input padding
ac.clearBadge();

9. Destroy Instance

Call instance.destroy() to remove all event listeners, restore the original autocomplete attribute, and remove the suggestions container from the DOM.

Destroy

Instance active. Click "Destroy" to tear down.

const ac = new Sadrazam.Autocomplete({
selector: '#ac-destroy',
source: '/api/countries'
});

// Later, to clean up:
ac.destroy();

10. Keyboard Navigation

All autocomplete instances support full keyboard navigation out of the box.

Key	Action
Arrow Down / Arrow Up	Navigate through suggestion items (skips items with data-autocomplete-disabled)
Enter / Tab	Select the currently highlighted suggestion and trigger onSelect
Escape	Close the suggestions dropdown

Try it

11. Static getInstance Method

Autocomplete.getInstance(element) returns the Autocomplete instance attached to the given input element, or undefined if none exists.

const input = document.querySelector('#my-input');
const ac = Sadrazam.Autocomplete.getInstance(input);

// Use the instance
ac.destroy();

12. Static Help Method

Call Sadrazam.Autocomplete.help() in the browser console to print all available configuration options with descriptions.

Console Sadrazam.Autocomplete.help()

// Open the browser DevTools console, then:
Sadrazam.Autocomplete.help();

// Output:
// Autocomplete
// selector: Target input element. String (class or id).
// source: Query endpoint. String.
// delay: Debounce delay in ms. Default: 250.
// cache: Cache results? Boolean. Default: false.
// minChars: Minimum chars before search. Default: 1.
// badge: Badge template with {field_name} placeholder. Optional.
// menuClass: CSS class for the container. String.
// onSelect: Callback on item selection.