flexdatalist

Quick Start

No jQuery. No build step. Drop two files and go.

<!-- CSS -->
<link rel="stylesheet"
      href="/path/to/jquery.flexdatalist.css">

<!-- JS (no jQuery needed) -->
<script src="/path/to/flexdatalist.js"></script>

<input type="text"
       class="flexdatalist"
       data-data="/api/items.json"
       data-search-in="name"
       data-min-length="1"
       name="item">

// init() is async — resolves after initial data loading is done
const [fd] = await Flexdatalist.init('#city', {
    url:            '/api/cities',
    searchIn:       ['name', 'zip'],
    valueProperty:  'id',
    textProperty:   '{name}, {zip}',
    minLength:      2,
});

// Chainable API
fd.setValue('42')
  .on('select:flexdatalist', e => console.log(e.detail));

// Get the stored value at any time
console.log(fd.getValue());

// When constructing directly, use .ready instead
const fd2 = new Flexdatalist(document.querySelector('#city'), opts);
await fd2.ready; // resolves once initial data is loaded

Data Sources

Three ways to provide data.

Flexdatalist.init('#el', {
  data: [
    {id: 1, label: 'Apple'},
    {id: 2, label: 'Banana'},
  ]
});

<input
  class="flexdatalist"
  data-data="items.json"
  data-search-in="label"
  name="item">

<input
  class="flexdatalist"
  data-url="/api/search"
  data-search-in="name"
  name="item">

{
  "results": [ { "id": 1, "name": "Paris" }, ... ],
  "options": { "url": "/api/next-endpoint" }  // optional — override options from server
}

Options

Set via JS constructor object or data-* attributes (camelCase → kebab-case). Options can also be changed at any time via fd.setOption(name, value).

API

All instance methods are chainable (return this) unless they return a value.

Static Methods

Options

Value

State

Search & Results

Event Binding

Lifecycle

Chaining Example

const [fd] = await Flexdatalist.init('#tags', {
    data:           myArray,
    multiple:       true,
    selectionRequired: true,
    limitOfValues:  5,
});

fd.setValue('1,2,3')           // pre-select three values
  .setOption('limitOfValues', 10) // change an option at runtime
  .on('change:flexdatalist', e => {
      console.log('changed', e.detail); // { value, text }
  })
  .on('select:flexdatalist', e => {
      console.log('selected item', e.detail); // the full item object
  });

// Later…
fd.addValue('4').disable();

// Or via native addEventListener
document.querySelector('#tags')
  .addEventListener('select:flexdatalist', e => console.log(e.detail));

Events

All events are dispatched as CustomEvent on the original <input> element. The payload is available at e.detail. Listen with fd.on(eventName, handler) or the native el.addEventListener(eventName, handler).

const el = document.querySelector('#city');

// Using the fd instance (chainable)
const [fd] = Flexdatalist.init(el, { url: '/api/cities' });
fd.on('select:flexdatalist', e => {
    console.log('Selected:', e.detail);
    // e.detail → { id: 42, name: 'Paris', country: 'FR' }
});

// Or using native DOM event (dispatched on the <input> element)
el.addEventListener('change:flexdatalist', e => {
    console.log('Value changed:', e.detail.value, '→', e.detail.text);
});

Keyboard Shortcuts

Available while the alias input is focused.

Framework Adapters

Use Flexdatalist as a native component in Vue, React, or Svelte. Each adapter is a thin wrapper (~5 kB) — the core does all the heavy lifting.

<script setup>
import { ref } from 'vue';
import { Flexdatalist } from 'flexdatalist-vue';
import 'flexdatalist/css';

const city = ref('');
</script>

<template>
  <Flexdatalist
    v-model="city"
    url="/api/cities"
    :min-length="2"
    @select="(item) => console.log(item)"
  />
</template>

import { Flexdatalist } from 'flexdatalist-react';
import 'flexdatalist/css';

function App() {
  return (
    <Flexdatalist
      url="/api/cities"
      minLength={2}
      onSelect={(item) =>
        console.log(item)
      }
    />
  );
}

<script>
  import { Flexdatalist }
    from 'flexdatalist-svelte';
  import 'flexdatalist/css';

  let city = '';
</script>

<Flexdatalist
  bind:value={city}
  url="/api/cities"
  minLength={2}
  on:select={(e) =>
    console.log(e.detail)
  }
/>

Migrating from jQuery Plugin

Key differences when upgrading from the original jquery.flexdatalist.js.

$('#el').flexdatalist({ url: '/api' });

$('#el').flexdatalist('value');
$('#el').flexdatalist('value', '42');
$('#el').flexdatalist('add', 'val');
$('#el').flexdatalist('remove', 'val');
$('#el').flexdatalist('disabled', true);
$('#el').flexdatalist('destroy');

$('#el').on('change:flexdatalist',
    function(evt, set, opts) {
        console.log(set.value, set.text);
    });

const [fd] = await Flexdatalist.init('#el', { url: '/api' });

fd.getValue();
fd.getText();                    // ['Paris', 'London']
fd.getText('string');            // 'Paris,London'
fd.getText(' | ');               // 'Paris | London'
fd.setValue('42');
fd.addValue('val');
fd.removeValue('val');
fd.disable();
fd.destroy();

fd.on('change:flexdatalist', e => {
    console.log(e.detail.value, e.detail.text);
});
// or: el.addEventListener('change:flexdatalist', e => ...)