Deprecation notice

At Speakap, we are migrating to a more responsive component library. As such, we will be migrating away from Selectivity, and we will no longer be maintaining this library. If you are interested in taking over ownership, please file an issue. Thanks for all the support!

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 a build with all features packed in.
• Compatibility. Selectivity.js can be used without any external libraries, but also offers a jQuery build that is compatible with both jQuery (including custom builds without Sizzle) and Zepto.js, and a build that is compatible with React. It's your choice how you want to use it.

Examples

Select a single city

<Selectivity.React
    allowClear={true}
    items={['Amsterdam', 'Antwerp'/*, ...*/]}
    placeholder='No city selected'
/>
    

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

Select multiple cities

<Selectivity.React
    items={['Amsterdam', 'Antwerp'/*, ...*/]}
    multiple={true}
    placeholder='Type to search a city'
/>
    

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

    

Select a city by country

<Selectivity.React
    allowClear={true}
    items={[{
        text: 'Austria',
        children: [ { id: 54, text: 'Vienna' } ]
    } /*, ...*/]}
    placeholder='No city selected'
/>
    

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

    

Select a city by timezone

<Selectivity.React
    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}
/>
    

$('#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

<Selectivity.React
    inputType='Email'
    placeholder='Type or paste 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.

<Selectivity.React
    ajax={{
        url: 'https://api.github.com/search/repositories',
        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) };
        },
        fetch: function(url, init, queryOptions) {
            return fetch(url)
                .then(function(response) {
                    if (response.ok) {
                        return response.json();
                    } else {
                        throw new Error('Unexpected AJAX response');
                    }
                })
                .then(function(data) {
                    return {
                        results: data.items.map(function(item) {
                            return {
                                id: item.id,
                                text: item.name,
                                description: item.description
                            };
                        }),
                        more: (data.total_count > queryOptions.offset + data.items.length)
                    };
                });
        }
    }}
    placeholder='Search for a repository'
    templates={{
        resultItem: function(item) {
            return (
                <div className='selectivity-result-item' data-item-id={item.id}>
                    <b>{item.text}</b><br />
                    {item.description}
                </div>
            );
        }
    }}
/>
    

$('#example-6').selectivity({
    ajax: {
        url: 'https://api.github.com/search/repositories',
        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) };
        },
        fetch: function(url, init, queryOptions) {
            return $.ajax(url).then(function(data) {
                return {
                    results: $.map(data.items, function(item) {
                        return {
                            id: item.id,
                            text: item.name,
                            description: item.description
                        };
                    }),
                    more: (data.total_count > queryOptions.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>'
            );
        }
    }
});
    

Setup

For setup instructions, please see the GitHub project page.

API

Older references: v2

jQuery

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.

React

Render a Selectivity component as follows:

<Selectivity.React {...options} />

This will create a <div> element in which the Selectivity control itself is rendered. Note that besides the options documented below, also some generic attributes for divs are allowed on this element ( className, onClick, onInput, style, ...).

Options

The following options are supported:

Methods

If you're using the jQuery API, 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' })

If you're using the React API, the methods to use are somewhat limited, because you are expected to use the component declaratively as much as possible. But for those methods available, you can call them like ordinary methods if you have a reference to the component instance:

this.refs.selectivity.getData()

add

(jQuery only, multiple-value inputs only)

Adds an item to the selection.

Examples:

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

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

clear

(jQuery only)

Clears the selection.

Example:

$(selector).selectivity('clear')

close

Closes the dropdown.

data

(React: Only getData() is provided)

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 with jQuery:
$(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' }])

// returns the current data with React:
this.refs.selectivity.getData()

destroy

(jQuery only)

Destroys the Selectivity instance.

Note: If you had initialized your Selectivity instance from a <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

(jQuery only, multiple-value inputs only)

Removes an item from the selection.

Examples:

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

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

rerenderSelection

(jQuery only)

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

(jQuery only)

Sets one or more options of the Selectivity instance.

Example:

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

value / val

(React: Only getValue() is provided)

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 with jQuery:
$(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])

// returns the current value with React:
this.refs.selectivity.getValue()

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.