Chosen: A Prototype Plugin by Harvest to Tame Unwieldy Select Boxes

Chosen is a Prototype plugin that makes long, unwieldy select boxes much more user-friendly.

Downloads Project Source Contribute

Looking for the jQuery version?

## Standard Select

Turns This
Into This

## Multiple Select

Turns This
Into This

## <optgroup> Support

Single Select with Groups
Multiple Select with Groups

## Selected and Disabled Support

Chosen automatically highlights selected options and removes disabled options.

Single Select
Multiple Select

## Hide Search on Single Select

The `disable_search_threshold` option can be specified to hide the search input on single selects if there are n or fewer options.

     new Chosen($("chosen_select_field"),{disable_search_threshold: 10});

## Default Text Support

Chosen automatically sets the default field text ("Choose a country...") by reading the select element's data-placeholder value. If no data-placeholder value is present, it will default to "Select an Option" or "Select Some Options" depending on whether the select is single or multiple. You can change these elements in the plugin js file as you see fit.

    <select data-placeholder="Choose a country..." multiple class="chosen-select">

Note: on single selects, the first element is assumed to be selected by the browser. To take advantage of the default text support, you will need to include a blank option as the first element of your select list.

## No Results Text Support

Setting the "No results" search text is as easy as passing an option when you create Chosen:

    new Chosen($("chosen_select_field"),{no_results_text: "Oops, nothing found!"});

Single Select
Multiple Select

## Limit Selected Options in Multiselect

You can easily limit how many options the user can select:

    new Chosen($("chosen_select_field"),{max_selected_options: 5});

If you try to select another option with limit reached `chosen:maxselected` event is triggered:

    $("chosen_select_field").observe("chosen:maxselected", function(evt) { ... });

## Allow Deselect on Single Selects

When a single select box isn't a required field, you can set `allow_single_deselect: true` and Chosen will add a UI element for option deselection. This will only work if the first option has blank text.

## Right-to-Left Support

You can set right-to-left text by setting `rtl: true`

     $(".chosen-select").chosen({rtl: true});

Single Right-to-Left Select
Multiple Right-to-Left Select

## Observing, Updating, and Destroying Chosen

- ### Observing Form Field Changes

  When working with form fields, you often want to perform some behavior after a value has been selected or deselected. Whenever a user selects a field in Chosen, it triggers a "change" event on the original form field. That lets you do something like this:

      $("#form_field").chosen().change( … );

  Note: Prototype doesn't offer support for triggering standard browser events. Event.simulate is required to trigger the change event when using the Prototype version.

- ### Updating Chosen Dynamically

  If you need to update the options in your select field and want Chosen to pick up the changes, you'll need to trigger the "chosen:updated" event on the field. Chosen will re-build itself based on the updated content.

      Event.fire($("form_field"), "chosen:updated");

- ### Destroying Chosen

  To destroy Chosen and revert back to the native select, call `destroy` on the Chosen instance:

      chosen = new Chosen($("form_field"));

      // ...later
      chosen.destroy();

## Custom Width Support

Using a custom width with Chosen is as easy as passing an option when you create Chosen:

    new Chosen($("chosen_select_field"),{width: "95%"});

Single Select
Multiple Select

## Labels work, too

Use labels just like you would a standard select

Click to Highlight Single Select
Click to Highlight Multiple Select

## Setup

Using Chosen is easy as can be.

1. Download the plugin and copy the chosen files to your app.
2. Activate the plugin by creating a new instance of Chosen: New Chosen(some_form_field,some_options);
3. Disco.

## FAQs

- ### Do you have all the available options documented somewhere?

  Yes! You can find them on the options page.

- ### Something doesn't work. Can you fix it?

  Yes! Please report all issues using the GitHub issue tracking tool. Please include the plugin version (jQuery or Prototype), browser and OS. The more information provided, the easier it is to fix a problem.

- ### What browsers are supported?

  All modern desktop browsers are supported (Firefox, Chrome, Safari and IE9). Legacy support for IE8 is also enabled. Chosen is disabled on iPhone, iPod Touch, and Android mobile devices (more information).

## Credits

- Concept and development by Patrick Filler for Harvest.
- Design and CSS by Matthew Lettini.
- Repository maintained by @pfiller, @kenearley, @stof, @koenpunt, and @tjschuck.
- Chosen includes contributions by many fine folks.

- Fork on Github
- Built by Harvest