Skip to content

Latest commit

 

History

History
267 lines (255 loc) · 9.86 KB

api.md

File metadata and controls

267 lines (255 loc) · 9.86 KB
Raw

Selectize API

Selectize controls can be controlled programmatically via the methods described in this section. When initializing the control, the "selectize" property is added on the original <select> / <input> element—this property points to the underlying Selectize instance.

// initialize the selectize control
var $select = $('select').selectize(options);

// fetch the instance
var selectize = $select[0].selectize;

Related Topics

Properties

Properties
Property Description
options An object containing the entire pool of options. The object is keyed by each object's value.
items An array of selected values.

Methods

Options
Method Description
addOption(data) Adds an available option, or array of options. If it already exists, nothing will happen. Note: this does not refresh the options list dropdown (use refreshOptions() for that).
updateOption(value, data) Updates an option available for selection. If it is visible in the selected items or options dropdown, it will be re-rendered automatically.
removeOption(value) Removes the option identified by the given value.
clearOptions() Removes all options from the control.
getOption(value) Retrieves the jQuery element for the option identified by the given value.
getAdjacentOption(value, direction) Retrieves the jQuery element for the previous or next option, relative to the currently highlighted option. The "direction" argument should be 1 for "next" or -1 for "previous".
refreshOptions(triggerDropdown) Refreshes the list of available options shown in the autocomplete dropdown menu.
Items
Method Description
clear(silent) Resets / clears all selected items from the control. If "silent" is truthy, no change event will be fired on the original input.
getItem(value) Returns the jQuery element of the item matching the given value.
addItem(value, silent) "Selects" an item. Adds it to the list at the current caret position. If "silent" is truthy, no change event will be fired on the original input.
removeItem(value, silent) Removes the selected item matching the provided value. If "silent" is truthy, no change event will be fired on the original input.
createItem(value, callback) Invokes the "create" method provided in the selectize options that should provide the data for the new item, given the user input. Once this completes, it will be added to the item list.
refreshItems() Re-renders the selected item lists.
Optgroups
Method Description
addOptionGroup(id, data) Registers a new optgroup for options to be bucketed into. The "id" argument refers to a value of the property in option identified by the "optgroupField" setting.
removeOptionGroup(id) Removes a single option group.
clearOptionGroups() Removes all existing option groups.
Events
Method Description
on(event, handler) Adds an event listener.
off(event, handler) Removes an event listener.
off(event) Removes all event listeners.
trigger(event, ...) Triggers event listeners.
Dropdown
Method Description
open() Shows the autocomplete dropdown containing the available options.
close() Closes the autocomplete dropdown menu.
positionDropdown() Calculates and applies the appropriate position of the dropdown.
Other
Method Description
destroy() Destroys the control and unbinds event listeners so that it can be garbage collected.
load(fn) Loads options by invoking the the provided function. The function should accept one argument (callback) and invoke the callback with the results once they are available.
focus() Brings the control into focus.
blur() Forces the control out of focus.
lock() Disables user input on the control (note: the control can still receive focus).
unlock() Re-enables user input on the control.
disable() Disables user input on the control completely. While disabled, it cannot receive focus.
enable() Enables the control so that it can respond to focus and user input.
getValue() Returns the value of the control. If multiple items can be selected (e.g. <select multiple>, this returns an array. If only one item can be selected, this returns a string.
setValue(value, silent) Resets the selected items to the given value.
setCaret(index) Moves the caret to the specified position ("index" being the index in the list of selected items).
isFull() Returns whether or not the user can select more items.
clearCache(template) Clears the render cache. Takes an optional template argument (e.g. "option", "item") to clear only that cache.

Related Objects

Search

Option Description Type
options Original search options. object
query The raw user input. string
tokens An array containing parsed search tokens. A token is an object containing two properties: "string" and "regex". array
total The total number of results. int
items A list of matched results. Each result is an object containing two properties: "score" and "id". array