---
title: Usage
description: Usage
---

## Basic Usage

In its simplest form, Selectize is initialized using an existing `<select>` element:

```html
<script>
  $(function () {
    $("select").selectize(options);
  });
</script>
```

## Advanced Usage

Configuration options are available for more advanced scenarios, including plugin support, remote data loading, custom rendering, and more.
The available settings are documented in the table below. See the [Demos](/docs/demos) page for examples of each option in action.

```html
<script type="text/javascript" src="selectize.js"></script>
<link rel="stylesheet" type="text/css" href="selectize.css" />
<script>
  $(function () {
    $("select").selectize({
      plugins: ["restore_on_backspace", "clear_button"],
      delimiter: " - ",
      persist: false,
      maxItems: null,
      valueField: "email",
      labelField: "name",
      searchField: ["name", "email"],
      options: [
        { email: "selectize@risadams.com", name: "Ris Adams" },
        { email: "someone@gmail.com", name: "Someone" },
        { email: "someone-else@yahoo.com", name: "Someone Else" },
      ],
    });
  });
</script>
```

### Glossary

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

### Configuration

| Setting                       | Type              | Default      | Description                                                                                                                                                                                                                                                                                                                                                             |
| ----------------------------- | ----------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **options**                   | array             | []           | 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 generate the `<option>`s automatically. |
| **items**                     | array             | []           | An array of the initial selected values. By default, this is populated from the original input element.                                                                                                                                                                                                                                                                 |
| **delimiter**                 | string            | ','          | 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.                           |
| **create**                    | boolean\|function | false        | Allows the user to create new items that aren't in the initial list of options.                                                                                                                                                                                                                                                                                         |
| **showAddOptionOnCreate**     | boolean           | true         | Toggles whether to show `'Add ...option...'` within the dropdown menu (if the create setting is enabled).                                                                                                                                                                                                                                                               |
| **createOnBlur**              | boolean           | false        | If true, when a user exits the field (clicks outside of input), a new option is created and selected (if the create setting is enabled).                                                                                                                                                                                                                                |
| **createFilter**              | RegExp\|Function  | string\|null | Specifies a Regular Expression or a string containing a regular expression that the current search filter must match to be allowed to be created. A predicate function may also take the filter text and return whether it is allowed.                                                                                                                                  |
| **highlight**                 | boolean           | true         | Toggles match highlighting within the dropdown menu.                                                                                                                                                                                                                                                                                                                    |
| **persist**                   | boolean           | true         | If false, items created by the user will not appear as available options once they are unselected.                                                                                                                                                                                                                                                                      |
| **openOnFocus**               | boolean           | true         | Show the dropdown immediately when the control receives focus.                                                                                                                                                                                                                                                                                                          |
| **maxOptions**                | int               | 1000         | The max number of items to render at once in the dropdown list of options.                                                                                                                                                                                                                                                                                              |
| **maxItems**                  | int               | null         | The max number of items the user can select. `1` makes the control mono-selection, `null` allows an unlimited number of items.                                                                                                                                                                                                                                          |
| **hideSelected**              | boolean           | null         | If true, the currently selected items will not be shown in the dropdown list of available options. This option defaults to true when in a multi-selection control and to false otherwise.                                                                                                                                                                               |
| **closeAfterSelect**          | boolean           | false        | If true, the dropdown will be closed after a selection is made.                                                                                                                                                                                                                                                                                                         |
| **closeDropdownThreshold**    | int               | 250          | The number of milliseconds to throttle the dropdown opening after it is closed by clicking on the control. Setting this to `0` will reopen the drop down after clicking on the control when the dropdown is open. This option does not affect multi-selects.                                                                                                            |
| **allowEmptyOption**          | boolean           | false        | If true, Selectize will treat any options with a "" value like normal. This defaults to false to accommodate the common `<select>` practice of having the first empty option act as a placeholder.                                                                                                                                                                      |
| **showEmptyOptionInDropdown** | boolean           | false        | If true, Selectize will show an option with value `""` in dropdown, if one does not exist, which is required when you want to select an empty option via `selectOnTab`. This requires `allowEmptyOption: true`.                                                                                                                                                         |
| **emptyOptionLabel**          | string            | '--'         | 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`.                                                                                                                          |
| **scrollDuration**            | int               | 60           | The animation duration (in milliseconds) of the scroll animation triggered when going [up] and [down] in the options dropdown.                                                                                                                                                                                                                                          |
| **deselectBehavior**          | string            | previous     | 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 the drop down the last element is highlighted. When this option is set to `top` it shifts the highlight to the top-most option. Valid options are `top` and `previous`.                                      |
| **loadThrottle**              | int               | 300          | 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.                                                                                                                                                      |
| **loadingClass**              | string            | 'loading'    | The class name is added to the wrapper element while awaiting the fulfillment of load requests.                                                                                                                                                                                                                                                                         |
| **placeholder**               | string            | undefined    | The placeholder of the control (displayed when nothing is selected/typed). Defaults to input element's placeholder unless this one is specified.                                                                                                                                                                                                                        |
| **preload**                   | boolean\|string   | false        | 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 the control receives focus.                                                                                                                                                                        |
| **dropdownParent**            | string            | null         | The element the dropdown menu is appended to. This option should be `'body'` or `null`. If `null`, the dropdown will be appended as a child of the Selectize control.                                                                                                                                                                                                   |
| **addPrecedence**             | boolean           | false        | If true, the "Add..." option is the default selection in the dropdown.                                                                                                                                                                                                                                                                                                  |
| **selectOnTab**               | boolean           | false        | If true, the tab key will choose the currently selected item.                                                                                                                                                                                                                                                                                                           |
| **diacritics**                | boolean           | true         | Enable or disable international character support.                                                                                                                                                                                                                                                                                                                      |
| **setFirstOptionActive**      | boolean           | false        | Enable setting the first option in the list as active.                                                                                                                                                                                                                                                                                                                  |

### Data/Searching

| Setting                   | Type           | Default     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------------- | -------------- | ----------- |   |
| **options**               | array          | []          | See above                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| **optgroups**             | array          | []          | Option groups that options will be bucketed into. If your element is a `<select>` with `<optgroup>`s, this property gets populated automatically. Ensure each object in the array has a property that matches the name of the `optgroupValueField`.                                                                                                                                                                                                                                                                                        |
| **dataAttr**              | string         | 'data-data' | The `<option>` attribute from which to read JSON data about the option.                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **valueField**            | string         | 'value'     | The property name to use as the value when an item is selected.                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| **optgroupValueField**    | string         | 'value'     | The name of the option group property that serves as its unique identifier.                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| **labelField**            | string         | 'text'      | The property name to render as an `option`/`item` label (not needed when custom rendering functions are defined).                                                                                                                                                                                                                                                                                                                                                                                                                          |
| **optgroupLabelField**    | string         | 'label'     | The property name to render as an option group label (not needed when custom rendering functions are defined).                                                                                                                                                                                                                                                                                                                                                                                                                             |
| **optgroupField**         | string         | 'optgroup'  | The property name by which to group items.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| **disabledField**         | string         | 'disabled'  | The property name to disabled option and `optgroup`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| **sortField**             | string\| array | '$order'    | 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, a direction can be set to either `'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 option will make results sorted primarily by match quality (descending). You can override the `$score` function. For more information, see the _sifter_ documentation. |
| **searchField**           | array          | ['text']    | An array of property names to analyze when filtering options.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| **searchConjunction**     | string         | 'and'       | When searching for multiple terms (separated by space), this is the operator used. This option can be set to `'and'` or `'or'`.                                                                                                                                                                                                                                                                                                                                                                                                            |
| **nesting**               | boolean        | false       | If `true`, nested fields will be available for search using dot-notation to reference them (e.g., the nested. property). _Warning: can reduce performance._                                                                                                                                                                                                                                                                                                                                                                                |
| **lockOptgroupOrder**     | boolean        | false       | If `true`, Selectize will make all option groups appear 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.                                                                                                                                                                                                                                                                                                                                               |
| **copyClassesToDropdown** | boolean        | true        | If `true` Copies the original input classes to the dropdown element.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |

### Event Callbacks

| Setting                        | Type     | Default | Description                                                                                                                                                                                                                                                                                                                                                    |
| ------------------------------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **load(query, callback)**      | function | null    | Invoked when new options are 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).                                                                                                                                                             |
| **score(search)**              | function | null    | 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. A search argument is a Search object. For an example, see the "GitHub" example. |
| **formatValueToKey(key)**      | string   | null    | Function to generate a 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 a (`'value' =>` 'value'`) combination. The provided function should return a unique key that is not an object or function.                                            |
| **onInitialize()**             | function | null    | Invoked once the control is completely initialized.                                                                                                                                                                                                                                                                                                            |
| **onFocus()**                  | function | null    | Invoked when the control gains focus.                                                                                                                                                                                                                                                                                                                          |
| **onBlur()**                   | function | null    | Invoked when the control loses focus.                                                                                                                                                                                                                                                                                                                          |
| **onChange(value)**            | function | null    | Invoked when the value of the control changes.                                                                                                                                                                                                                                                                                                                 |
| **onItemAdd(value, $item)**    | function | null    | Invoked when an item is selected.                                                                                                                                                                                                                                                                                                                              |
| **onItemRemove(value)**        | function | null    | Invoked when an item is deselected.                                                                                                                                                                                                                                                                                                                            |
| **onClear()**                  | function | null    | Invoked when the control is manually cleared via the clear() method.                                                                                                                                                                                                                                                                                           |
| **onDelete(values)**           | function | null    | Invoked when the user attempts to delete the current selection.                                                                                                                                                                                                                                                                                                |
| **onOptionAdd(value, data)**   | function | null    | Invoked when a new option is added to the list of available options.                                                                                                                                                                                                                                                                                           |
| **onOptionRemove(value)**      | function | null    | Invoked when an option is removed from the available options.                                                                                                                                                                                                                                                                                                  |
| **onDropdownOpen($dropdown)**  | function | null    | Invoked when the dropdown opens.                                                                                                                                                                                                                                                                                                                               |
| **onDropdownClose($dropdown)** | function | null    | Invoked when the dropdown closes.                                                                                                                                                                                                                                                                                                                              |
| **onType(str)**                | function | null    | Invoked when the user types while filtering options.                                                                                                                                                                                                                                                                                                           |
| **onLoad(data)**               | function | null    | Invoked when new options have been loaded and added to the control (via the load option or load API method).                                                                                                                                                                                                                                                   |

### Custom Rendering

Custom rendering functions. Each function should accept two arguments: `data` and `escape`, and must 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.

| Function            | Description                                                                                                                           |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **option**          | An option in the dropdown list of available options.                                                                                  |
| **item**            | An item the user has selected.                                                                                                        |
| **option_create**   | The "create new" option is 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 header and options.                   |
