| General |
| Option |
Description |
Type |
Default |
delimiter |
The string to separate items by. This option is only used when Selectize is instantiated from a <input type="text"> element. |
string |
',' |
diacritics |
Enable or disable international character support. |
boolean |
true |
create |
Allows the user to create a new items that aren't in the list of options. This option can be any of the following: "true" (default behavior), "false" (disabled), or a function that accepts two arguments: "input" and "callback". The callback should be invoked with the final data for the option. |
mixed |
false |
createOnBlur |
If true, when user exits the field (clicks outside of input or presses ESC) new option is created and selected (if `create`-option is enabled).
| boolean |
false |
createFilter |
Specifies a RegExp or 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. |
mixed |
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. |
int |
∞ |
hideSelected |
If true, the items that are currently selected will not be shown in the dropdown list of available options. |
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. |
int |
300 |
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 |
Sets if the "Add..." option should be the default selection in the dropdown. |
boolean |
false |
selectOnTab |
If true, the tab key will choose the currently selected item. |
boolean |
false |
| Data / Searching |
| Option |
Description |
Type |
Default |
options |
Options available to select; array of objects. If your element is <select> with <option>s specified this property gets populated accordingly. Setting this property is convenient if you have your data as an array and want to automatically generate the <option>s. |
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' |
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).<br><br>
For more information, see the <a href="https://github.com/brianreavis/sifter.js#sifterjs">sifter documentation</a>.
</td>
<td valign="top"><code>string|array</code></td>
<td valign="top"><code>'$order'</code></td>
</tr>
<tr>
<td valign="top"><code>searchField</td>
<td valign="top">An array of property names to analyze when filtering options.</td>
<td valign="top"><code>array</code></td>
<td valign="top"><code>['text']</code></td>
</tr>
<tr>
<td valign="top"><code>searchConjunction</td>
<td valign="top">When searching for multiple terms (separated by a space), this is the operator used. Can be "and" or "or".</td>
<td valign="top"><code>string</code></td>
<td valign="top"><code>'and'</code></td>
</tr>
<tr>
<td valign="top"><code>optgroupOrder</td>
<td valign="top">An array of optgroup values that indicates the order they should be listed in in the dropdown. If not provided, groups will be ordered by the ranking of the options within them.</td>
<td valign="top"><code>array</code></td>
<td valign="top"><code>null</code></td>
</tr>
<tr>
<th valign="top" colspan="4" align="left"><a href="#callbacks" name="callbacks">Callbacks</a></th>
</tr>
<tr>
<th valign="top" align="left">Option</th>
<th valign="top" align="left">Description</th>
<th valign="top" align="left">Type</th>
<th valign="top" align="left">Default</th>
</tr>
<tr>
<td valign="top"><code>load(query, callback)</code></td>
<td valign="top">Invoked when new options should be loaded from the server.</td>
<td valign="top"><code>function</code></td>
<td valign="top"><code>null</code></td>
</tr>
<tr>
<td valign="top"><code>score(search)</code></td>
<td valign="top">Overrides the scoring function used to sort available options. The provided function should return a <strong>function</strong> 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 <a href="#search">Search</a> object. For an example, see the <a href="https://github.com/brianreavis/selectize.js/blob/master/examples/github.html">"GitHub" example</a>.</td>
<td valign="top"><code>function</code></td>
<td valign="top"><code>null</code></td>
</tr>
<tr>
<td valign="top"><code>onInitialize()</code></td>
<td valign="top">Invoked once the control is completely initialized.</td>
<td valign="top"><code>function</code></td>
<td valign="top"><code>null</code></td>
</tr>
<tr>
<td valign="top"><code>onChange(value)</code></td>
<td valign="top">Invoked when the value of the control changes.</td>
<td valign="top"><code>function</code></td>
<td valign="top"><code>null</code></td>
</tr>
<tr>
<td valign="top"><code>onItemAdd(value, $item)</code></td>
<td valign="top">Invoked when an item is selected.</td>
<td valign="top"><code>function</code></td>
<td valign="top"><code>null</code></td>
</tr>
<tr>
<td valign="top"><code>onItemRemove(value)</code></td>
<td valign="top">Invoked when an item is deselected.</td>
<td valign="top"><code>function</code></td>
<td valign="top"><code>null</code></td>
</tr>
<tr>
<td valign="top"><code>onClear()</code></td>
<td valign="top">Invoked when the control is manually cleared via the clear() method.</td>
<td valign="top"><code>function</code></td>
<td valign="top"><code>null</code></td>
</tr>
<tr>
<td valign="top"><code>onDelete(values)</code></td>
<td valign="top">Invoked when the user attempts to delete the current selection.</td>
<td valign="top"><code>function</code></td>
<td valign="top"><code>null</code></td>
</tr>
<tr>
<td valign="top"><code>onOptionAdd(value, data)</code></td>
<td valign="top">Invoked when a new option is added to the available options list.</td>
<td valign="top"><code>function</code></td>
<td valign="top"><code>null</code></td>
</tr>
<tr>
<td valign="top"><code>onOptionRemove(value)</code></td>
<td valign="top">Invoked when an option is removed from the available options.</td>
<td valign="top"><code>function</code></td>
<td valign="top"><code>null</code></td>
</tr>
<tr>
<td valign="top"><code>onDropdownOpen($dropdown)</code></td>
<td valign="top">Invoked when the dropdown opens.</td>
<td valign="top"><code>function</code></td>
<td valign="top"><code>null</code></td>
</tr>
<tr>
<td valign="top"><code>onDropdownClose($dropdown)</code></td>
<td valign="top">Invoked when the dropdown closes.</td>
<td valign="top"><code>function</code></td>
<td valign="top"><code>null</code></td>
</tr>
<tr>
<td valign="top"><code>onType(str)</code></td>
<td valign="top">Invoked when the user types while filtering options.</td>
<td valign="top"><code>function</code></td>
<td valign="top"><code>null</code></td>
</tr>
<tr>
<td valign="top"><code>onLoad(data)</code></td>
<td valign="top">Invoked when new options have been loaded and added to the control (via the "load" option or "load" API method).</td>
<td valign="top"><code>function</code></td>
<td valign="top"><code>null</code></td>
</tr>
<tr>
<th valign="top" colspan="4" align="left"><a href="#rendering" name="rendering">Rendering</a></th>
</tr>
<tr>
<td valign="top"><code>render</code></td>
<td valign="top">
Custom rendering functions. Each function should accept two arguments: "data" and "escape".
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.
<table width="100%">
<tr>
<td valign="top"><code>option</code></td>
<td valign="top">An option in the dropdown list of available options.</td>
</tr>
<tr>
<td valign="top"><code>item</code></td>
<td valign="top">An item the user has selected.</td>
</tr>
<tr>
<td valign="top"><code>option_create</code></td>
<td valign="top">The "create new" option at the bottom of the dropdown. The data contains one property: "input" (which is what the user has typed).</td>
</tr>
<tr>
<td valign="top"><code>optgroup_header</code></td>
<td valign="top">The header of an option group.</td>
</tr>
<tr>
<td valign="top"><code>optgroup</code></td>
<td valign="top">The wrapper for an optgroup. The "html" property in the data will be the raw html of the optgroup's header and options.</td>
</tr>
</table>
</td>
<td valign="top"><code>object</code></td>
<td valign="top"></td>
</tr>
|