Examples

Select a single city

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

Select multiple cities

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

Select a city by country

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

Select a city by timezone

$('#example-4').select3({
    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').select3({
    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').select3({
    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: (offset + data.items.length > data.total_count)
            };
        }
    },
    placeholder: 'Search for a repository',
    templates: {
        resultItem: function(item) {
            return (
                '<div class="select3-result-item" data-item-id="' + item.id + '">' +
                    '<b>' + escape(item.text) + '</b><br>' +
                    escape(item.description) +
                '</div>'
            );
        }
    }
});

API

Call $(selector).select3(options) to initialize a Select3 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 Select3 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 Select3 control.

The following options are supported:

Methods

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

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

add

(multiple-value inputs only)

Adds an item to the selection.

Examples:

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

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

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).select3('data')

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

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

focus

Focuses the search input.

open

Opens the dropdown.

remove

(multiple-value inputs only)

Removes an item from the selection.

Examples:

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

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

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), Select3 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 Select3 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).select3('value')

$(selector).select3('val')

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

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

Events

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

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