Skip to content

Latest commit

 

History

History
301 lines (298 loc) · 12.4 KB

usage.md

File metadata and controls

301 lines (298 loc) · 12.4 KB

Selectize – Usage

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

Options

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
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. 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
Data / Searching
Option Description Type Default
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 The name of the property to sort by. This is only used when the score of two or more items is identical. string null
sortDirection Sort direction ("asc" or "desc"). string 'asc'
searchField An array of property names to analyze when filtering options. array ['text']
optgroupOrder 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. array null
Callbacks
Option Description Type Default
load(query, callback) Invoked when new options should be loaded from the server. 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
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". 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