Benefits

• Rich UI. Select boxes made by selectivity have rich functionality, work out of the box and are customizable.
• Modular. Selectivity's modular approach is aimed to make it easy to create custom builds with just the features that you care about and to easily swap modules for custom ones.
• Light-weight. Selectivity.js is smaller than comparable selection libraries, even if you're using the "full" build with all features packed in.
• Compatibility. Selectivity.js can be used with both jQuery and Zepto.js and is compatible with jQuery builds without Sizzle.

Examples

Select a single city

$('#example-1').selectivity({
    allowClear: true,
    items: ['Amsterdam', 'Antwerp'/*, ...*/],
    placeholder: 'No city selected'
});

Select multiple cities

$('#example-2').selectivity({
    items: ['Amsterdam', 'Antwerp'/*, ...*/],
    multiple: true,
    placeholder: 'Type to search a city'
});

Select a city by country

$('#example-3').selectivity({
    allowClear: true,
    items: [{
        text: 'Austria',
        children: [ { id: 54, text: 'Vienna' } ]
    } /*, ...*/],
    placeholder: 'No city selected'
});

Select a city by timezone

$('#example-4').selectivity({
    allowClear: true,
    items: [{
        id: '+00:00',
        text: 'Western European Time Zone',
        submenu: {
            items: [
                { id: 4, text: 'Barcelona' }
                /*, ...*/
            ],
            showSearchInput: true
        }
    } /*, ...*/],
    placeholder: 'No city selected',
    showSearchInputInDropdown: false
});

Enter one or more email addresses

$('#example-5').selectivity({
    inputType: 'Email',
    placeholder: 'Type or paste email addresses'
});

Search a GitHub repository

Note: If this example stops working, please wait a few minutes. There is an active rate-limit in the GitHub API.

$('#example-6').selectivity({
    ajax: {
        url: 'https://api.github.com/search/repositories',
        dataType: 'json',
        minimumInputLength: 3,
        quietMillis: 250,
        params: function(term, offset) {
            // GitHub uses 1-based pages with 30 results, by default
            return { q: term, page: 1 + Math.floor(offset / 30) };
        },
        processItem: function(item) {
            return {
                id: item.id,
                text: item.name,
                description: item.description
            };
        },
        results: function(data, offset) {
            return {
                results: data.items,
                more: (data.total_count > offset + data.items.length)
            };
        }
    },
    placeholder: 'Search for a repository',
    templates: {
        resultItem: function(item) {
            return (
                '<div class="selectivity-result-item" data-item-id="' + item.id + '">' +
                    '<b>' + escape(item.text) + '</b><br>' +
                    escape(item.description) +
                '</div>'
            );
        }
    }
});

API v2

Call $(selector).selectivity(options) to initialize a Selectivity instance on the element specified by the given selector. The element should be a <div> element which will be used as container to render the Selectivity control in. If the element is a <select> element instead, this element will be used for initializing some of the options below after which it is replaced with a <div> element to contain the Selectivity control.

The following options are supported:

Methods

Methods are invoked by passing the name of the method, followed by any arguments, to the selectivity() function. Example:

$(selector).selectivity('data', { id: 1, text: 'Amsterdam' })

add

(multiple-value inputs only)

Adds an item to the selection.

Examples:

$(selector).selectivity('add', 1)

$(selector).selectivity('add', { id: 1, text: 'Amsterdam' })

clear

Clears the selection.

Example:

$(selector).selectivity('clear')

close

Closes the dropdown.

data

Sets or gets the data of the selection. If no argument is given, the current data is returned. Otherwise, the data is set to the argument given.

When new data is set, the appropriate change event is automatically generated, unless triggerChange is set to false.

Examples:

// returns the current data:
$(selector).selectivity('data')

// sets new data on a single-value input:
$(selector).selectivity('data', { id: 1, text: 'Amsterdam' })

// sets new data on a multiple-value input:
$(selector).selectivity('data', [{ id: 1, text: 'Amsterdam' }, { id: 2, text: 'Antwerp' }])

destroy

Destroys the Selectivity instance.

Note: If you had initialized your Selectivity instance from an <input> or <select> element, that element is gone forever and you won't get it back by destroying the Selectivity instance.

focus

Focuses the search input.

open

Opens the dropdown.

remove

(multiple-value inputs only)

Removes an item from the selection.

Examples:

$(selector).selectivity('remove', 1)

$(selector).selectivity('remove', { id: 1, text: 'Amsterdam' })

rerenderSelection

Re-renders the selection.

Normally the UI is automatically updated whenever the selection changes, but you may want to call call this method explicitly if you've updated the selection with the triggerChange option set to false.

setOptions

Sets one or more options of the Selectivity instance.

Example:

$(selector).selectivity('setOptions', { readOnly: true })

value / val

Sets or gets the value of the selection. If no argument is given, the current value is returned. Otherwise, the value is set to the argument given.

Note: When setting the value of the selection, the full data (including the text properties) is updated as well. In order to detect the right text for the ID(s), Selectivity will inspect the items array to look up the corresponding item(s). If no items have been provided, it is assumed the text should be equal to the ID. If this is not what you want, you may want to pass the initSelection option to the Selectivity instance to override this process.

When a new value is set, the appropriate change event is automatically generated, unless triggerChange is set to false.

Examples:

// returns the current value:
$(selector).selectivity('value')

$(selector).selectivity('val')

// sets a new value on a single-value input:
$(selector).selectivity('value', 1)

// sets a new value on a multiple-value input:
$(selector).selectivity('value', [1, 2])

Events

All of these events are emitted on the element to which the Selectivity instance is attached and can be listened to using jQuery's on() method.

Note: If you have used a <select> element for initializing the Selectivity instance, you should realize it is replaced by a <div> element after the initialization. Any events will be triggered on the latter.

More information

For more information, see the GitHub page.