Need help with zelect?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

398 Stars 42 Forks Do What The F*ck You Want To Public License 81 Commits 13 Opened issues


From <select> to something more 2012

Services available


Need anything else?

Contributors list

# 298,555
46 commits
# 97,325
1 commit


Build Status

It's just yet another <select>.

>>> Example <<<

>>> Download <<<

  • Small, ~ 300 LOC
  • Zero base CSS, roll your own
  • Customizable (well, at least workaroundable)
  • Handles asynchronous paged loading of large option lists (read: AJAX-ready-and-enabled)
  • Initializable in a detached or hidden DOM node
  • Programmatically selectable and changeable
  • Unit-tested

for opts in $.fn.zelect(opts)

option default type usage
throttle 300 ms. Delay for throttling keyups for filtering/loading option items based on a search term. 0 makes things synchronous.
loader undefined function(term, page, callback): Array[Item] Function for loading a pageful of option items. See example
renderItem item.label || item.toString() function(item, term): String, DOM, jQuery, etc. Function to render a single option item. See example
initial undefined item Initially selected item
placeholder undefined String, DOM, jQuery, etc Placeholder text or HTML to show when no initial selection. The first option item is selected by default if this is left undefined.
noResults "No results for '$query'" function(query?): String, DOM, jQuery, etc. Function to render a no-hits text.
regexpMatcher /(^|\s)term/i function(term): RegExp Function to create a RegExp to filter <select>-based options with.

An item is any javascript data structure: String, Object, Array, whatever.

Minimal Setup

If the option list is known on the client, finite and manageable, use HTML:

  First Option
  Another Option
  Third option


Asyncronous Paged Setup

If the option list is server-backed, infinite or close to it, use

  initial: 'Third',
  loader: function(term, page, callback) {
    callback(['First for page '+page, 'Second', 'Third'])

Callback expects an array. Elements in the array can be anything that renderItem can handle.

zelect will load the next page of results from

whenever the option list is scrolled to the bottom. It will stop trying to load more once the callback is called with an empty array.

Subscribing to Changes

These events are triggered on the <select>-element:

event args triggered when
ready - zelect is ready: first results have loaded and the initial selection has been made
change event, item Selected item changed. 2nd parameter is the item itself.

In addition:

If the zelect is <select>-backed,

will return the value of the currently selected option.

will always return the currently selected item.

Programmatically Changing The Selection

$('select').zelectItem(myNewItemThatIWantToSelectNow, fireChangeEvent)
will do that.

Whether a change event fires can be controlled with the

boolean. The default is true.

Programmatically Refreshing an Externally Updated Item

$('select').refreshZelectItem(myUpdatedItem, function(item) { return item._id })
will replace and rerender the item matching myUpdatedItem._id with the new version.

No change events are fired.

Programmatically Resetting the Zelect

will reset the query to an empty string, load the first results and select the first item.

A change event will fire.


zelect comes with no base css. Make your own.

For inspiration, see an example.

Initial Selection

When first rendered, zelect determines the initially selected item in this order:

  1. opts.initial
    if defined
  2.  if 
    not defined
  3. Render placeholder text from
    if defined
  4. Select the first option from the list if there are items
  5. Render noResults text without a term

Custom Option Item Rendering Example

  renderItem: function(item, term) {
    return $('').addClass('my-item').text(item.label).highlight(term)

Highlights matches of the search term in the option text, by using e.g. jquery.highlight.js.

Ajax Loader Example

  loader: function(term, page, callback) {
    $.get('/search', { query: term, page: page }, function(arrayOfItems) {

Uses a GET to retrieve paged results from a server.

Convoluted Semi-Real-World Example

$('select').on('ready', function() { $('form').enable() })
$('select').on('change', function(evt, item) { $('form').val( })
  throttle: 150,
  placeholder: $('').text('Which one...'),
  loader: loader,
  renderItem: renderer,
  noResults: noResultser

function loader(term, page, callback) { $.get('/q', { q:term, p:page }).then(function(items) { var result = _(items).map(function(item) { return { text:item.content, img:item.imageUrl || 'default.png', id:item.uniqueId } } callback(result) } }

function renderer(item, term) { return $('

') .append($('').attr('src', item.img)) .append($('').addClass('content').text(item.label)) }

function noResultser(term) { return $('').addClass('no-results').text(term + "didn't hit anything.") }


We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.