# flexselect

## a jQuery plugin

### What?

Flexselect is a jQuery plugin that turns select boxes into flex-matching incremental-finding controls. Think of it as Quicksilver squished into a select box. Download, view the examples, and enjoy.

Flexselect takes the select box, and creates a hidden input element to track the associated value and creates a text input for the selection. It uses the LiquidMetal scoring algorithm to narrow the selection.

### Examples

On the left is a traditional select box. On the right is a flexselect control. Just start typing to narrow the selection.

#### Pick a U.S. President (not pre-selected)

#### Pick an animal (pre-selected)

TODO: Add more examples for common option overrides

### How?

First, load the default styles, jQuery, the LiquidMetal scoring algorithm, and the plugin.

    <link rel="stylesheet" href="flexselect.css" type="text/css" media="screen" />
    <script src="jquery.min.js" type="text/javascript"></script>
    <script src="liquidmetal.js" type="text/javascript"></script>
    <script src="jquery.flexselect.js" type="text/javascript"></script>

It's important that the styles come before the javascript. Now, let's convert your select boxes into some flexselect goodness on DOM ready:

    jQuery(document).ready(function() {
      $("select.flexselect").flexselect();
    });

This will turn all `select` elements with a class of `flexselect` into a flex matching masterpiece:

    <select class="flexselect">
      <option value="1">George Washington</option>
      <option value="2">John Adams</option>
      <option value="3">Thomas Jefferson</option>
      ...
    </select>

Flexselect also supports some options to override the default behavior:

Experimental Ad Hoc Entry: (The technique for handling this might change) It's possible to allow ad hoc entries into a flexselect input field that don't match the values in the underlying select box. Suppose you had a select box like this:

    <select name="email" class="flexselect"> ... </select>

If you enable flexselect with custom options that look like this:

    $("select.flexselect").flexselect({
      allowMismatch: true,
      inputNameTransform:  function(name) { return "new_" + name; }
    });

The input text field that replaces the select box will not only allow you to match custom values that weren't in the select box, but it will have a name attribute of `new_email` assigned to it. You can customize the `inputNameTransform` function however you like. The argument value passed to it is the original name from the select box.

When the form is submitted (with allowMismatch set to true), the original `email` param will be an empty string and the `new_email` param will be the value of the text in the input box.

TODO: Add a detailed list of all the options

### Where?

Download the "stable" release.

The code is hosted on GitHub: http://github.com/rmm5t/jquery-flexselect. Go on, live on the edge.

### Who?

Flexselect was built by Ryan McGeary (@rmm5t) and was inspired by jQuery.quickselect, MooTools Select Autocompleter, Live Search with QuickSilver, and jQuery LiveSearch.