jQuery plugin: gentleSelect

Intro

gentleSelect is a jQuery plugin for transforming select boxes into a skinnable alternative. The selection list can be rendered with multiple columns/rows to present larger datasets in a more manageable format. It recognizes the multiple attribute on select boxes and does the right thing automatically.

Here's a gentleSelect box compared to a standard select box

And here's select box with multiple selection enabled, processed using gentleSelect with maxDisplay option set to 3 (try selecting more than 3 items):

Note that unlike a standard select box, one does not need to use Ctrl-Click (Cmd-Click on macs) to select multiple items.

There is much to be done on the flexibility and robustness front, and we welcome contributions and bug fixes. Feel free to fork the project and send us pull requests!

Download

Latest Release : gentleSelect v0.1.3.1
If you're feeling brave, download the Development Version

TODO

calculate default itemWidth automatically when columns or rows specified
implement option to fix width of select box (based on longest entry)
implement option to add CSS class (simplify customization)

Usage

To use this plugin, one simply needs to load jQuery and the JS/CSS scripts for gentleSelect, then attach it to your select boxes on DOM ready:

<script type="text/javascript" 
        src="http://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js"></script>
<script type="text/javascript" src="gentleSelect/jquery-gentleSelect.js"></script>

<link type="text/css" href="gentleSelect/jquery-gentleSelect.css" rel="stylesheet" />

<script type="text/javascript">
    $(document).ready(function() {
        $('#selector').gentleSelect(); // apply gentleSelect with default options
    });
</script>

This produces a standard single-column select box as such

Options

title

You can specify a heading for the selection box using the title option.

For example,

    $('#selector').gentleSelect({
        title: "Select a colour"
    });

columns & itemWidth

Specifies the number of columns used to display the selection. The number of rows is calculated accordingly. When specifying columns, the itemWidth option must also be set. This value must be large enough to fit the longest option.

For example, can be implemented using:

    $('#selector').gentleSelect({
        columns: 3,
        itemWidth: 100,
    });

rows & itemWidth

There may be situations where one might think it would be more suitable to fix the number of rows instead, allowing the columns to spread out as required.

This can be achieved by specifying the rows and itemWidth options.

For example, can be implemented using:

    $('#selector').gentleSelect({
        rows: 5,
        itemWidth: 30,
    });

openEffect & closeEffect

Effects to use for displaying and hiding the selection menu. Possible options are 'fade' and 'slide' (default).

openSpeed & closeSpeed

Specifies the speed of the open/close animation. This value is specified in milliseconds; higher values indicate slower animations, not faster ones. The strings 'slow' and 'fast' can be supplied to indicate an animation duration of 600 and 200 milliseconds.

The default value is 400.

For example, can be implemented using:

    $('#selector').gentleSelect({
        columns: 3,
        itemWidth: 100,
        openEffect: "fade",
        openSpeed: "slow"
    });

hideOnMouseOut

Specifies whether the selection menu should be hidden when the mouse leaves the selection box. This is true by default. Set to false to disable this behaviour.

For example, (menu only disappears when something is selected)

    $('#selector').gentleSelect({
        columns: 3,
        itemWidth: 100,
        hideOnMouseOut: false
    });

This option has no effect if multiple is enabled on the selection box.

maxDisplay

Specifies the maximum number of items to display when multiple selection is enabled. When the number of selected items exceed a specified value. say 5, then only the first 5 items are displayed (delimited by comma) followed by "..." to indicate that some selected items are hidden. The default value is 0 (no limit).

Methods

update

If you update the value of the select box using an external script, you can update the display by calling the update function.

    // assssuming gentleSelect() previously initialised
    $('#selector').val(3).gentleSelect("update");