Flexdatalist - jQuery autocomplete/datalist

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	Event instance Object with value and text 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	Event instance Selected item object Options	Triggered every time the user selects an option from results.
before:flexdatalist.data	Event instance	Triggered before loading all data.
after:flexdatalist.data	Event instance Data	Triggered after loading all data.
before:flexdatalist.search	Event instance Keyword(s) Data	Triggered before search (before loading all necessary data).
after:flexdatalist.search	Event instance Keyword(s) Data Matched items	Triggered after search (before showing results).
show:flexdatalist.results	Event instance Result(s)	Triggered before showing the results.
shown:flexdatalist.results	Event instance Result(s)	Triggered after showing the results.
item:flexdatalist.results	Event instance Item	Triggered on each rendered result item.
empty:flexdatalist.results	Event instance	Triggered when nothing found.
before:flexdatalist.remove	Event instance	Triggered before removing value.
after:flexdatalist.remove	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 ;)