jQueryflexdatalist

Flexdatalist is (another) jQuery autocomplete plugin with support for <datalist>.


On submit send selected country's continent...

24 KB minified — 8 KB gzipped

Examples

The yellow highlight is only present on this demo's stylesheet.


Datalist

Using data from <datalist> as a suggestion (the standard behavior).

Value

Force the selection of an option from <datalist>

Value

Multiple Values

Multiple values from <datalist> (Use enter ↵ to add values)

Value

Multiple options from <datalist> (selection required)

Value

Search disabled

Prevent flexdatalist from doing the search and just show data.

Value

Data from remote file

Load data from file countries.json.

Like with <datalist> behavior, show the results as a suggestion.
Please note in the HTML that in order to search for value(s) property(ies) in a JSON, we set the option searchIn to name that matches the property for country name in JSON.

Value

... with multiple values:

Value

Now with the option selectionRequired to true:

Value

Let's add some visibleProperties to results.
Since we are searching for country's name, 'name' is automatically an visibleProperties, but to add more, we simply set visibleProperties with ["name","capital","continent"].

Value

But if we want to search the country name, but send its id on form submit? That's what valueProperty is for.

Value

Let's continue to send the selected id but changing textProperty to {capital}, {name}, {continent}.

Value

... with multiple values:

Value

And if we want to pre-select a country by is id...

Value

... or select multiple countries by setting multiple id's:

Value

Or send all selected country's properties... just by setting valueProperty to *.

Value

Multiple values.

Value

Send all country's properties on select or string in input.

Value

Limit the number of values

Just set limitOfValues to a value greater than 0.

Value

Search by word

Set searchByWord to true to enable it. It will break the keyword into individual words and search them independently.

e.g: Write papua guinea

Value

Toggle value(s) on click/tap

Just set toggleSelected to true and on click/tap, it will toggle the value.

Value

Show all results on focus

Just set minLength to 0 and on focus, it will show all results.

Value

Field Relatives

The option relatives allows you to send to remote server the values of relative inputs. This is useful when you need to filter the results on the server depending on other input(s) value(s).

In the example below, for each remote search, will send the relatives values so that you can, for example, filter results according to input#relative (previous input) current value.

Value

Chained Relatives

The option chainedRelatives disables the input until relative inputs are filled.

In the example below, with chainedRelatives set to true, if the input below is disabled, is because it's waiting for input#chained_relative (previous input) to get selected.

Value

... input is disabled? Its just waiting for input#chained_relative2 (previous input) to get selected.

Value

How to install

Download the plugin's latest version from Github repository.


Include the CSS file jquery.flexdatalist.min.css

<link href="/path/to/jquery.flexdatalist.min.css" rel="stylesheet" type="text/css">

Include the JS file jquery.flexdatalist.min.js

<script src="/path/to/jquery.flexdatalist.min.js"></script>


By default the plugin selects all input.flexdatalist's:

<input type="text" class="flexdatalist" >

... but you can use any selector:

$('.my-input').flexdatalist();
<input type="text" class="my-input" >

Options

Plugin configuration options


NOTE If you like, you can reset the options after initialization. Example: $('.my-input').flexdatalist('url', '/path/to/mydata');

Option Type Default Description
data string|array null Data source. Array of objects or a URL to JSON string/file.

NOTE If using a URL, it will load the data once.

url string null URL to remote data source. This is useful when data is just too big to pass to data option.
The request parameters are:
  • keyword: Search keyword
  • load: Array of values flexdatalist is trying to load. Usually happens when setting the value directly, like on init or when adding a value.
  • selected: Currently selected value(s)
  • contain: The searchContain option value
  • Only on POST options: Flexdatalist options
NOTE It will keep requesting the server for data whenever is appropriate. If possible, filter also on the server side to improve performance.
NOTE If data is also set, it will merge the remote data with current loaded data set in data.

TIP! Flexdatalist allows you to control option(s) from the backend. Expects a server response like:

{
   "results":[
      ...
   ],
   "options":{
      "url":"/next-time-send-to-this-url"
   }
}
params object {} Additional parameters on AJAX requests.
cache boolean true Cache for (repeated) remote requests.
cacheLifetime int 60 Cache lifetime (in seconds).
multiple boolean false Accept multiple values
disabled boolean false Disabled field(s)
minLength integer 2 Search if there are n or greater characters.

If set to 0 it will show all results on input focus.

NOTE If set to 0 we recommend using maxShownResults to improve performance.

searchContain boolean false By default, Flexdatalist's search matches starting at the beginning of a word. Setting this option to true allows matches starting from anywhere within a word. This is especially useful for options that include a lot of special characters or phrases in ()s and []s.
searchDisabled boolean false Disable search of keyword in data.
searchByWord boolean false If set to true, it will split the keyword's words and search for them individually.
maxShownResults integer 100 Maximum number of results to show.
groupBy string null Group results by given property's name value.
selectionRequired boolean false Selection from search results is required.
focusFirstResult boolean false Focus first result.
searchIn string|array ["label"] Name of property (or properties) where it will search.
searchDelay integer 300 For each key press, delay search in n miliseconds. This prevents one search per keystroke.
noResultsText string 'No results found for "{keyword}"'

Text that will show when no results are found. If empty string, it won't show message.

visibleProperties array []

Name of properties values that will appear with the search result.

Each property value will be wrapped with a <span class="item item-the_property_name">Property Value</span> so that its possible to style the appearance of additional information in the results.

textProperty string null

The text that will be visible to the user.

You can use {property_name} to be replaced with property value.

valueProperty string|object/array null

The property name that when selected its value will be sent with the form.

If you wanna send properties from selected item, set this option to *

iconProperty string 'thumb'

Name of property that holds path to image to be added as icon.

normalizeString function null

This allows you to normalize the strings being compared before comparison.

Useful when using tools like latinize.

Example:


$.flexdatalist({
    normalizeString: function (string) {
        return latinize(string);
    }
});

relatives string|jQuery instance null

Input relatives. Accepts field(s) selector(s) or an jQuery instance of the fields.

The relatives values will be sent with each request to remote server.

Example:


$.flexdatalist({
    relatives: '#user_full_name'
});

chainedRelatives boolean false

If set to true the flexdatalist field will be disabled until all the relatives are filled.

toggleSelected boolean false

If set to true, in multiple values allows you to toggle the presence of the value.

requestType string 'get'

Allows you to set the type of request it will make.

requestContentType string 'x-www-form-urlencoded'

If you prefer to send data to remote server as JSON, set this option to 'json'

resultsProperty string 'results'

Flexdatalist expects the data from server to be in the main response object or responseObject.results but you can change the name of property that holds the results.

keywordParamName string 'keyword'

By default, flexdatalist sends the keyword in request parameter with name keyword.

allowDuplicateValues boolean false

As the name suggests, it allows multiple options with the same value.

limitOfValues integer 0

Limit the number of values in a multiple input.

0 to disable limit.

removeOnBackspace boolean true

On backspace key, remove previous value (multiple values setting)

valuesSeparator string ',' Delimiter used in multiple values.

NOTE If you like, you can reset the options after initialization. Example: $('.my-input').flexdatalist('url', '/path/to/mydata');

Methods

Plugin methods


Method Description
$.val() Alias of $.flexdatalist('value') Get value as string. If passed value as argument, it will set it.
$.flexdatalist('value') Will return value either as string, JSON object or array.
$.flexdatalist('value', 'My new value') Set value
$.flexdatalist('add', 'add_me') Add value on multiple fields.
$.flexdatalist('remove', 'remove_me') Remove value on multiple fields.
$.flexdatalist('toggle', 'value') Toggle value on multiple fields.
$.flexdatalist('option_name') Get option
$.flexdatalist('option_name', 'new_value') Set option
$.flexdatalist('disabled') Returns true if disabled, false otherwise.
$.flexdatalist('disabled', true or false) Enable/Disable input.
$.flexdatalist('destroy') Destroy flexdatalist instance.
$.flexdatalist('reset')
or
$.flexdatalist()
Reset flexdatalist instance.

Events


Name Parameters Description
change:flexdatalist
  1. Event instance
  2. Object with value and text
  3. Options
Triggered every time the value in input changes.

$('input.flexdatalist').on('change:flexdatalist', function(event, set, options) {
    console.log(set.value);
    console.log(set.text);
});
select:flexdatalist
  1. Event instance
  2. Selected item object
  3. Options
Triggered every time the user selects an option from results.
before:flexdatalist.data
  1. Event instance
Triggered before loading all data.
after:flexdatalist.data
  1. Event instance
  2. Data
Triggered after loading all data.
before:flexdatalist.search
  1. Event instance
  2. Keyword(s)
  3. Data
Triggered before search (before loading all necessary data).
after:flexdatalist.search
  1. Event instance
  2. Keyword(s)
  3. Data
  4. Matched items
Triggered after search (before showing results).
show:flexdatalist.results
  1. Event instance
  2. Result(s)
Triggered before showing the results.
shown:flexdatalist.results
  1. Event instance
  2. Result(s)
Triggered after showing the results.
item:flexdatalist.results
  1. Event instance
  2. Item
Triggered on each rendered result item.
empty:flexdatalist.results
  1. Event instance
Triggered when nothing found.
before:flexdatalist.remove
  1. Event instance
Triggered before removing value.
after:flexdatalist.remove
  1. Event instance
Triggered after value was removed.

NOTE jQuery change will also be triggered.

Why?


After searching and not finding a standalone, lite (not dependent on jQueryUI), autocomplete that did everything I needed for a project, I created Flexdatalist.

Along with many other cool features, Flexdatalist allows you to style the list of suggested data/values, which is not possible at the moment with browser's native <datalist>.

Hope it's useful to you as it is to me. Enjoy ;)

Copyright © 2016