usage.md

Selectize – Usage

<scripttype="text/javascript" src="selectize.js"></script><linkrel="stylesheet" type="text/css" href="selectize.css" /><script>$(function(){$('select').selectize(options);});</script>

Glossary

• Config / configuration: the initial settings of Selectize, given at initialization.
• Settings: the current settings of Selectize, might be updated. Accessible with the setting property of the Selectize object.
• Options: the list of objects to display. Each object must have a property with an unique value to identify the option; the property name is defined by the valueField setting. Option objects must also have a property with the label to display (as tag, in the drop down, etc.); the property name is defined by the labelField setting. The options can have other properties, ignored, unless referenced by other settings, like sortField or searchField.
• Items: the list of selected options. Or more exactly, the list of the values of the selected options.

Configuration

General
Setting	Description	Type	Default
options	An array of the initial options available to select; array of objects. By default this is populated from the original input element. If your element is a <select> with <option>s specified this property gets populated automatically. Setting this property is convenient if you have your data as an array and want to automatically generate the <option>s.	array	[]
items	An array of the initial selected values. By default this is populated from the original input element.	array	[]
delimiter	The string to separate items by. When typing an item in a multi-selection control allowing creation, then the delimiter, the item is added. If you paste delimiter-separated items in such control, the items are added at once. The delimiter is also used in the getValue API call on a text <input> tag to separate the multiple values.	string	','
create	Allows the user to create new items that aren't in the initial list of options. This setting can be any of the following: true, false (disabled), or a function to process input. The function can take one of two forms: synchronous (with signature function(input){} or asynchronous (with signature function(input, callback). In the synchronous case, the function should return an object for the options (eg, with defaults: return { 'value': value, 'text': text };). The asynchronous version should invoke the callback with the result in the same format as the object above (eg, callback( { 'value': value, 'text': text});)	boolean/function	false
createOnBlur	If true, when user exits the field (clicks outside of input), a new option is created and selected (if create setting is enabled).	boolean	false
createFilter	Specifies a RegExp or a string containing a regular expression that the current search filter must match to be allowed to be created. May also be a predicate function that takes the filter text and returns whether it is allowed.	RegExp|string|function	null
highlight	Toggles match highlighting within the dropdown menu.	boolean	true
persist	If false, items created by the user will not show up as available options once they are unselected.	boolean	true
openOnFocus	Show the dropdown immediately when the control receives focus.	boolean	true
maxOptions	The max number of items to render at once in the dropdown list of options.	int	1000
maxItems	The max number of items the user can select. 1 makes the control mono-selection, null allows an unlimited number of items.	int	1
hideSelected	If true, the items that are currently selected will not be shown in the dropdown list of available options.	boolean	false
closeAfterSelect	If true, the dropdown will be closed after a selection is made.	boolean	false
allowEmptyOption	If true, Selectize will treat any options with a "" value like normal. This defaults to false to accomodate the common <select> practice of having the first empty option to act as a placeholder.	boolean	false
scrollDuration	The animation duration (in milliseconds) of the scroll animation triggered when going [up] and [down] in the options dropdown.	int	60
loadThrottle	The number of milliseconds to wait before requesting options from the server or null. If null, throttling is disabled. Useful when loading options dynamically while the user types a search / filter expression.	int	300
loadingClass	The class name added to the wrapper element while awaiting the fulfillment of load requests.	string	'loading'
placeholder	The placeholder of the control (displayed when nothing is selected / typed). Defaults to input element's placeholder, unless this one is specified.	string	undefined
preload	If true, the load function will be called upon control initialization (with an empty search). Alternatively it can be set to 'focus' to call the load function when control receives focus.	boolean/string	false
dropdownParent	The element the dropdown menu is appended to. This should be 'body' or null. If null, the dropdown will be appended as a child of the Selectize control.	string	null
addPrecedence	If true, the "Add..." option is the default selection in the dropdown.	boolean	false
selectOnTab	If true, the tab key will choose the currently selected item.	boolean	false
diacritics	Enable or disable international character support.	boolean	true
Data / Searching
Setting	Description	Type	Default
options	See above	array	[]
optgroups	Option groups that options will be bucketed into. If your element is a <select> with <optgroup>s this property gets populated automatically. Make sure each object in the array has a property named whatever optgroupValueField is set to.	array	[]
dataAttr	The <option> attribute from which to read JSON data about the option.	string	'data-data'
valueField	The name of the property to use as the value when an item is selected.	string	'value'
optgroupValueField	The name of the option group property that serves as its unique identifier.	string	'value'
labelField	The name of the property to render as an option / item label (not needed when custom rendering functions are defined).	string	'text'
optgroupLabelField	The name of the property to render as an option group label (not needed when custom rendering functions are defined).	string	'label'
optgroupField	The name of the property to group items by.	string	'optgroup'
disabledField	The name of the property to disabled option and optgroup.	string	'disabled'
sortField	A single field or an array of fields to sort by. Each item in the array should be an object containing at least a field property. Optionally, direction can be set to 'asc' or 'desc'. The order of the array defines the sort precedence. Unless present, a special `$score` field will be automatically added to the beginning of the sort list. This will make results sorted primarily by match quality (descending). You can override the `$score` function. For more information, see the sifter documentation.	string|array	'$order'
searchField	An array of property names to analyze when filtering options.	array	['text']
searchConjunction	When searching for multiple terms (separated by space), this is the operator used. Can be 'and' or 'or' .	string	'and'
lockOptgroupOrder	If truthy, Selectize will make all optgroups be in the same order as they were added (by the `$order` property). Otherwise, it will order based on the score of the results in each.	boolean	false
copyClassesToDropdown	Copy the original input classes to the dropdown element.	boolean	true
Callbacks
Setting	Description	Type	Default
load(query, callback)	Invoked when new options should be loaded from the server. Called with the current query string and a callback function to call with the results when they are loaded (or nothing when an error arises).	function	null
score(search)	Overrides the scoring function used to sort available options. The provided function should return a function that returns a number greater than or equal to zero to represent the score of an item (the function's first argument). If 0, the option is declared not a match. The search argument is a Search object. For an example, see the "GitHub" example.	function	null
onInitialize()	Invoked once the control is completely initialized.	function	null
onFocus()	Invoked when the control gains focus.	function	null
onBlur()	Invoked when the control loses focus.	function	null
onChange(value)	Invoked when the value of the control changes.	function	null
onItemAdd(value, $item)	Invoked when an item is selected.	function	null
onItemRemove(value)	Invoked when an item is deselected.	function	null
onClear()	Invoked when the control is manually cleared via the clear() method.	function	null
onDelete(values)	Invoked when the user attempts to delete the current selection.	function	null
onOptionAdd(value, data)	Invoked when a new option is added to the available options list.	function	null
onOptionRemove(value)	Invoked when an option is removed from the available options.	function	null
onDropdownOpen($dropdown)	Invoked when the dropdown opens.	function	null
onDropdownClose($dropdown)	Invoked when the dropdown closes.	function	null
onType(str)	Invoked when the user types while filtering options.	function	null
onLoad(data)	Invoked when new options have been loaded and added to the control (via the load option or load API method).	function	null
Rendering
render	Custom rendering functions. Each function should accept two arguments: data and escape and return HTML (string or DOM element) with a single root element. The escape argument is a function that takes a string and escapes all special HTML characters. This is very important to use to prevent XSS vulnerabilities. option An option in the dropdown list of available options. item An item the user has selected. option_create The "create new" option at the bottom of the dropdown. The data contains one property: input (which is what the user has typed). optgroup_header The header of an option group. optgroup The wrapper for an optgroup. The html property in the data will be the raw html of the optgroup's header and options.	object