Configuration and API

Configuration and API

Pass options when initializing Chosen:

$(".chosen-select").chosen({
  disable_search_threshold: 10,
  no_results_text: "Nothing matched",
  width: "100%"
});

The live Options and API reference is the canonical table of defaults. This page groups the most useful settings by task.

jQuery plugin interface

The jQuery adapter exposes $.fn.chosen.Constructor and $.fn.chosen.AbstractConstructor for integrations that extend Chosen. If another plugin used the same name, noConflict() restores that plugin and returns Chosen's plugin function:

var chosenPlugin = $.fn.chosen.noConflict();
$.fn.myChosen = chosenPlugin;
$(".chosen-select").myChosen();

Regular .chosen() calls remain unchanged. Prefer per-control options over editing a constructor prototype when configuring one select.

Shared initialization defaults

Set defaults before creating controls when the same options apply throughout an application:

$.fn.chosen.defaults = {placeholder_text_single: "Choose an item"};
$(".chosen-select").chosen();
$(".project-select").chosen({placeholder_text_single: "Choose a project"});

For Prototype, set Chosen.defaults before calling new Chosen(...). Each adapter has its own defaults object. You can replace the object or change its properties. Defaults apply only to controls initialized afterward; explicit options for one control take precedence. Chosen copies the options one level deep for each new instance. The native select's data-placeholder or placeholder attribute still takes precedence over placeholder options. See the live defaults examples in both demo adapters.

Per-select data attributes

Both legacy adapters can read scalar options from the native select. Replace underscores in an option name with hyphens in the attribute:

<select data-disable-search="true" data-allow-single-deselect="true"
        data-width="100%" data-placeholder-text-single="Choose a project">
  <option value=""></option>
  <option>Atlas</option>
  <option>Beacon</option>
</select>

Explicit JavaScript options take precedence over these attributes, which take precedence over adapter-wide defaults. Boolean values must be true or false; numeric values must be nonnegative whole numbers. String settings use their literal value, and data-width="false" leaves width to CSS. Invalid or unknown attributes are ignored. Callbacks and object options, including search_matcher and parser_config, still require JavaScript. Attributes are read at initialization, so destroy and reinitialize Chosen after changing them. The existing data-placeholder, data-no_results_text, and data-create_option_text attributes retain their previous precedence.

Try the jQuery or Prototype example. This screenshot shows the selected value and clear button configured by the select's attributes:

Search

• disable_search and disable_search_threshold
• search_contains, search_in_values, and case_sensitive_search
• search_word_boundary for locale-specific word starts while keeping built-in highlighting
• highlight_prefix_matches to prefer a visible label-prefix match for keyboard selection during contains searches
• split_search_terms and enable_split_word_search
• min_search_length, max_search_length, and search_delay
• group_search and max_shown_results
• normalize_search_text for accent-aware matching
• search_matcher for fully custom filtering; it replaces Chosen's built-in matching and highlighting
• search_input_type for integrations that need the previous type="text" search field instead of the current type="search" default
• Per-option aliases through data-search-text
• A data-chosen-always-visible marker for options such as “Other” that should remain available while searching

For example, an alias lets “espresso” find Café without changing its label:

<option value="cafe" data-search-text="coffee espresso">Café</option>

Use normalize_search_text to transform both the query and option text before matching. A search_matcher(query, item) callback gets the parsed option or group and returns a boolean; custom matches cannot highlight a substring because the callback returns no match position. min_search_length hides results until enough text is entered, while search_delay waits before updating results. max_search_length limits the text passed into matching, without limiting what the user can type.

JavaScript's default word boundary can split a name after an accented letter. Use a trusted regular-expression source for the letters in your options:

$(".chosen-select").chosen({
  search_word_boundary: "^|[^A-Za-zÆØÅæøå]"
});

With this opt-in setting, “Møl” finds “Frank Møller”, while “ller” does not. The default remains ^|\\s|\\b in a JavaScript string; search_contains: true bypasses the boundary setting. React uses searchWordBoundary. Try the jQuery, Prototype, Vanilla, or React example.

For punctuation-prefixed values, combine enable_split_word_search: false with search_contains: true to match only from the start of an option. A query for <01M finds <01M Fund, but not Other <01M Fund. Without the start-only setting, search_contains can match later in the option too. Try the jQuery or Prototype demo.

With search_contains: true, a search for “a” can match React before Angular because Chosen keeps the source option order. Set highlight_prefix_matches: true to initially highlight Angular for Enter selection while leaving both the result list and native select in their original order. The preference applies to rendered, selectable results; a custom search_matcher keeps its own behavior. Compare the jQuery and Prototype demos.

To offer a fallback choice even when nothing matches, mark the original option:

<option value="other" data-chosen-always-visible>Other</option>

The marked option stays in its native order and remains selectable when the search has no ordinary match. It also appears beyond max_shown_results, but Select all does not select it unless its label actually matches the query. Hidden options and display_disabled_options: false still take precedence. After adding or removing the marker, trigger chosen:updated. Try the jQuery or Prototype country demo.

Selection

• allow_single_deselect (blank first option required; a focused closed control also clears with Backspace or Delete)
• max_selected_options
• deselect_selected_results to remove selections from result rows
• max_items_shown, more_items_text, and show_fewer_items_text
• paste_multiple_values for selecting existing options from delimited pasted text
• display_selected_options and display_disabled_options
• backspace_deletes_choices and single_backstroke_delete
• multiselect_allow_tab_to_select
• hide_results_on_select
• open_on_label_click to choose whether associated labels also open the dropdown

max_selected_options limits selection. max_items_shown only shortens the visible list of selected chips. With deselect_selected_results: true, enabled selected items remain in the dropdown with a remove mark and can be deselected there by pointer or Enter. Disabled selected items remain unchanged.

With paste_multiple_values: true on a multiple select, a paste containing commas, semicolons, tabs, or line breaks selects matching existing options. Values match exactly; labels match without case sensitivity when unique. Unknown, disabled, hidden, ambiguous, and over-limit entries remain in the search field for editing. Chosen does not create options. The native select receives one input and change event if the selection changes. Try the jQuery or Prototype demo.

Bulk actions

Bulk actions are opt-in and affect enabled options. Select all applies to the current filtered result set; Deselect all clears enabled selections while preserving disabled selected options.

$(".chosen-select").chosen({
  allow_select_all: true,
  allow_deselect_all: true,
  select_all_text: "Select visible",
  deselect_all_text: "Clear selections"
});

With an empty search, Command/Ctrl+A selects all and Command/Ctrl+Shift+A deselects all. With search text present, Command/Ctrl+A retains normal text-selection behavior.

Shift-select a range

Set shift_select_range: true on a multiple select to add a range of visible options. Select an item, then Shift-click another. Chosen selects the options between them, skips disabled options, preserves choices outside the range, and respects max_selected_options. The anchor must remain visible under the current search filter. Omit the setting to keep the existing click behavior. React uses shiftSelectRange; source markup can use data-shift-select-range="true" in the classic and Vanilla editions.

Try it in the jQuery, Prototype, Vanilla, or React demo.

Display

• placeholder_text_single and placeholder_text_multiple
• placeholder_text_multiple_selected for an optional hint after a multiple-select choice
• placeholder_text as a shared fallback for either select type
• no_results_text, no_results_template, and results_count_text
• display_selected_value and include_group_label_in_selected
• width, dropdown_width, dropdown_position, mobile_fullscreen, recalculate_width_on_update, and rtl
• inherit_select_classes, inherit_option_classes, and inherit_optgroup_classes

Set placeholder_text_multiple_selected: "Add another..." to show a hint in the multiple select's search field after someone chooses an item. The original select remains the source of submitted values. Omit the option to keep the existing empty search field. React uses placeholderTextMultipleSelected, and source markup can use data-placeholder-text-multiple-selected. Try the jQuery, Prototype, Vanilla, or React demo.

Set inherit_optgroup_classes: true to copy each selected option's parent optgroup classes to its chip in a multiple select. For example, give a Cars group class="group-cars" and a Bikes group class="group-bikes", then style .search-choice.group-cars and .search-choice.group-bikes in your CSS. This does not change native values, option labels, or classes by default. React uses inheritOptgroupClasses; Vanilla uses the same snake-case option as classic Chosen. Try the jQuery, Prototype, Vanilla, or React demo.

Use no_results_template: "No match for {search}." when a translation needs the search term inside or at the beginning of the message. The optional template overrides no_results_text; leaving out {search} omits the term. Both the message and search term render as text. React uses noResultsTemplate, and native select markup can use data-no-results-template. Try the jQuery, Prototype, Vanilla, or React example.

For a select populated after initialization, set recalculate_width_on_update: true and trigger chosen:updated after adding options. Chosen then measures the native select again and updates the control width. The setting defaults to false, and an explicit width takes precedence. If the select's parent is hidden, Chosen keeps its previous width until a later update can measure it. Try the jQuery or Prototype demo.

Setting dropdown_width also presents the results as a separate floating surface, with complete corners and a small gap from the closed control. Use a wider value for long result labels, max-content for intrinsic sizing, or 100% when the dropdown should stay the same width but retain the detached treatment. Right-to-left dropdowns align to the control's right edge.

Set mobile_fullscreen: true to give a picker the visible viewport on touch screens up to 600px wide. It includes a Close button, lets the results scroll, and follows the on-screen keyboard. Wider screens keep the anchored dropdown. The setting defaults to false; the original select still supplies the form value and events. React uses mobileFullscreen. You can also use data-mobile-fullscreen="true" on a classic or Vanilla source select.

Try the jQuery, Prototype, Vanilla, or React demo.

Placeholder precedence is data-placeholder, native placeholder, the type-specific option, the shared placeholder_text option, then Chosen's default. A single select needs an empty first option for a placeholder and allow_single_deselect. An explicitly empty placeholder is respected; it does not fall back to Chosen's default text.

Summarizing selected choices

For a multiple select with many selected values, max_items_shown keeps the visible chip list short. This only changes the display; every selected option remains selected in the original <select>. The summary button expands the hidden chips, then offers “Show fewer...” to return to the compact view. max_selected_options serves a different purpose: it limits selection.

$(".chosen-select").chosen({max_items_shown: 2});

The default summary reads “Show 2 more...” when two choices are hidden. Use more_items_text and show_fewer_items_text to localize or replace the labels. See the live options reference for the defaults.

Creating options from search

Option creation is opt-in. With create_option: true, Chosen offers to append the typed search as a selected option when no result matches. A function can be passed instead if the application needs to validate or save the option itself; that callback receives the search text with the Chosen instance as this. The callback must add the option itself, for example by calling this.select_append_option({value: text, text: text}) after validation.

$(".chosen-select").chosen({
  create_option: true,
  persistent_create_option: true,
  skip_no_results: true,
  create_option_text: "Add project:"
});

persistent_create_option keeps the action available alongside partial matches, unless the search exactly matches an existing option. skip_no_results hides the no-results row when creation is enabled. Set the text per control with data-create_option_text; use data-no_results_text for the no-results message. Both attributes override their corresponding options.

Select attributes and parser data

Chosen displays native <option> text as plain text. When the option has no text, it uses the label attribute instead, so an option such as <option value="kodiak" label="Kodiak Bear"></option> appears as “Kodiak Bear” and still submits kodiak. Text keeps precedence when both are present. An empty value with a whitespace-only label remains a placeholder. React uses the equivalent { value: 'kodiak', label: 'Kodiak Bear' } option data. For a blank first choice, write <option value=""></option>. Text content such as   or   is whitespace, not a null value. If value is omitted, the browser derives it from that text, and Chosen preserves the native value. This differs from a whitespace-only label attribute on an otherwise empty option, where there is no text content or value to select. Nested HTML inside an option is not copied into result rows or selected choices. no_results_text and create_option_text, including their data-* overrides, are also plain text; HTML markup in those labels appears literally.

• select-by-group lets a multiple select choose available options by clicking an optgroup label.
• readonly prevents changes but keeps the original select enabled for form submission. Trigger chosen:updated after changing it.
• selected, disabled, and hidden on options retain their native meanings.
• A native placeholder attribute is used when data-placeholder is absent.
• data-search-text adds search aliases without changing displayed labels.
• parser_config: {copy_data_attributes: true} copies each option's data-* attributes into its parsed result data for advanced integrations. Alias search does not require this setting.

For broader examples, see the jQuery demo and Prototype demo. The options table lists defaults.

Events from Chosen

Bind application behavior to the source select:

$(".chosen-select").on("change", function (event, details) {
  console.log(this.value, details);
});

$(".chosen-select").on("chosen:no_results", function (event, details) {
  details.no_results.find("span").text("Try another spelling");
});

$(".chosen-select").on("chosen:no_results_clear", function (event, details) {
  console.log("No-results message cleared for", details.search_term);
});

In the jQuery adapter, Chosen includes selected for a new value and deselected for a removed value in the extra input and change event parameter. Switching a single select includes both; clearing it includes only deselected. The initial blank placeholder is not a deselected value. Prototype emits native input and change events without this extra parameter.

Available events include chosen:ready, chosen:maxselected, chosen:search_updated, chosen:showing_dropdown, chosen:hiding_dropdown, chosen:search, chosen:no_results, and chosen:no_results_clear. The two no-results events include search_term and the rendered no_results row; the clear event fires before removal. jQuery receives a collection, while Prototype receives an element. Vanilla dispatches equivalent native events on its source select with these values in event.detail. React uses onNoResults(query) and onNoResultsClear(query) callbacks.

Events sent to Chosen

$(".chosen-select").trigger("chosen:updated");
$(".chosen-select").trigger("chosen:open");
$(".chosen-select").trigger("chosen:close");

Use chosen:activate to focus the control and chosen:open to open its dropdown, including when it is already focused. Use chosen:updated after changing options, attributes, disabled state, readonly state, or labels on the source select. A native form reset restores the original select value and refreshes Chosen's display without emitting a change event.