| 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 |
- ||||||||||
showAddOptionOnCreate |
- Toggles whether to show 'Add ...option...' within the dropdown menu (if create setting is enabled). |
- boolean |
- true |
- ||||||||||
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 |
- null |
- ||||||||||
hideSelected |
- If true, the items that are currently selected will not be shown in the dropdown list of available options. This defaults to true when in a multi-selection control, to false otherwise. |
- boolean |
- null |
- ||||||||||
closeAfterSelect |
- If true, the dropdown will be closed after a selection is made. | -boolean |
- false |
- ||||||||||
closeDropdownThreshold |
- The number of milliseconds to throttle the opening of the dropdown after it is closed by clicking on the control. Setting this to 0 will reopen the dropdown after clicking on the control when the dropdown is open. This does not affect multi-selects. | -int |
- 250 |
- ||||||||||
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 |
- ||||||||||
showEmptyOptionInDropdown |
- If true, Selectize will show an option with value `""` in dropdown, if one does not exist; which is required when you want to select a empty option via `selectOnTab`. This requires `allowEmptyOption: true`. | -boolean |
- false |
- ||||||||||
emptyOptionLabel |
- If `showEmptyOptionInDropdown: true` and an option with value `""` in dropdown does not exist, an option with `""` value is created, the label/text of the option can be set via this option, this requires `showEmptyOptionInDropdown: true`. | -string |
- '--' |
- ||||||||||
scrollDuration |
- The animation duration (in milliseconds) of the scroll animation triggered when going [up] and [down] in the options dropdown. | -int |
- 60 |
- ||||||||||
deselectBehavior |
- If an option is selected, the same option is highlighted/marked active in the dropdown, pressing backspace on the input control removes the option and in dropdown the previous element is highlight. When this option is set to `top` it shifts the highlight to the topmost option. Valid options are `top` and `previous`. | -string |
- previous |
- ||||||||||
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 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' |
- ||||||||||
| 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 |
+ ||||||||||
showAddOptionOnCreate |
+ Toggles whether to show 'Add ...option...' within the dropdown menu (if create setting is enabled). |
+ boolean |
+ true |
+ ||||||||||
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 |
+ null |
+ ||||||||||
hideSelected |
+ If true, the items that are currently selected will not be shown in the dropdown list of available options. This defaults to true when in a multi-selection control, to false otherwise. |
+ boolean |
+ null |
+ ||||||||||
closeAfterSelect |
+ If true, the dropdown will be closed after a selection is made. | +boolean |
+ false |
+ ||||||||||
closeDropdownThreshold |
+ The number of milliseconds to throttle the opening of the dropdown after it is closed by clicking on the control. Setting this to 0 will reopen the dropdown after clicking on the control when the dropdown is open. This does not affect multi-selects. | +int |
+ 250 |
+ ||||||||||
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 |
+ ||||||||||
showEmptyOptionInDropdown |
+ If true, Selectize will show an option with value `""` in dropdown, if one does not exist; which is required when you want to select a empty option via `selectOnTab`. This requires `allowEmptyOption: true`. | +boolean |
+ false |
+ ||||||||||
emptyOptionLabel |
+ If `showEmptyOptionInDropdown: true` and an option with value `""` in dropdown does not exist, an option with `""` value is created, the label/text of the option can be set via this option, this requires `showEmptyOptionInDropdown: true`. | +string |
+ '--' |
+ ||||||||||
scrollDuration |
+ The animation duration (in milliseconds) of the scroll animation triggered when going [up] and [down] in the options dropdown. | +int |
+ 60 |
+ ||||||||||
deselectBehavior |
+ If an option is selected, the same option is highlighted/marked active in the dropdown, pressing backspace on the input control removes the option and in dropdown the previous element is highlight. When this option is set to `top` it shifts the highlight to the topmost option. Valid options are `top` and `previous`. | +string |
+ previous |
+ ||||||||||
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 |
+ ||||||||||
setFirstOptionActive |
+ Enable setting the first option in the list as active. | +boolean |
+ false |
+ ||||||||||
| 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 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' |
+ ||||||||||
nesting |
If true, nested fields will be available for search using dot-notation to reference them (e.g. nested.property). *Warning: can reduce performance.* | boolean |
false |
||||||||||
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 |
- ||||||||||
formatValueToKey(key) |
- Function to generate key for a new item created from input when create is set to true, to generate a `'key' => 'value'` combination. Without using this function, it will result in `'value' => 'value'` combination. The provided function should return a key that is not object or function. | -string |
- 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.
-
|
- object |
- - | ||||||||||
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 |
+ ||||||||||
formatValueToKey(key) |
+ Function to generate key for a new item created from input when create is set to true, to generate a `'key' => 'value'` combination. Without using this function, it will result in `'value' => 'value'` combination. The provided function should return a key that is not object or function. | +string |
+ 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.
+
|
+ object |
+ + | ||||||||||