Philippe Masset

Engineer at Buffer.

jQuery.SimpleSelect, make every <select> fully customizable

jQuery.SimpleSelect replaces every <select> with a HTML + CSS alternative. The result is 100% stylable selects.

Live examples

Answer:

Other live examples

A SimpleSelect behaves the same way a <select> does

You can:

  • Press tab to jump to and from a SimpleSelect
  • Press up and down navigation keys to navigate between options
  • Type some letters to highlight the closest matching option (e.g. typing "fr" to highlight "France")
  • Press enter to select the highlighted option
  • Listen to the change event
  • Disable the SimpleSelect, dynamically change its contents when the select's options have changed…

There are only two things a SimpleSelect cannot do:

  • Handle the multiple attribute
  • Handle the disabled attribute on an <optgroup>

Basic usage

HTML

<select>
    <option>Option 1</option>
    <option>Option 2</option>
    <option>Option 3</option>
</select>​

JavaScript

$("select").simpleselect();

Generated HTML

The whole point of this plugin is to transform a <select> into HTML so that it's possible to style it however you want. Here's the HTML generated from the above <select> once the plugin has been called, and a couple of things that are good to know about it:

  • If the <select> has an id attribute, the generated SimpleSelect will have the same id, prepended with simpleselect_
  • Every <select> on which the plugin has been called has the class .simpleselected, and is hidden inside a <div> with the class .hidden_select_container

Click to view the generated HTML

<div class="hidden_select_container">
    <select class="simpleselected">
        <option>Option 1</option>
        <option>Option 2</option>
        <option>Option 3</option>
    </select>
</div>
<div class="simpleselect">
    <div class="placeholder">Option 1</div>
    <div class="options">
        <div class="option">Option 1</div>
        <div class="option">Option 2</div>
        <div class="option">Option 3</div>
    </div>
</div>

Less basic usage

To see examples of SimpleSelects with groups of options and other attributes, head back to the live examples.

SimpleSelect options

fadingDuration (number, default: 0)

If greater than zero, the options list will be displayed and hidden by animating its opacity over the given duration (in milliseconds).

containerMargin (number, default: 5)

Margin left between the options list and the window's edges when the SimpleSelect is active (in pixels).

containerMargin option illustration

displayContainerInside (string, default: "window")

By default, the options list is displayed inside the window only, meaning it can't overflow past the window's bounds. If displayContainerInside is set to "document", the options list will be displayed within the whole document's edges, instead of the window's.

SimpleSelect methods

These methods can either be called on the original <select> or on the SimpleSelect (or several of them).
Examples of these methods being used can be found in the live examples.

.simpleselect("setActive")

Set a SimpleSelect in an active state (show its options list).

.simpleselect("setInactive")

Set a SimpleSelect in an inactive state (hide its options list).

.simpleselect("refreshContents")

Re-populate a SimpleSelect's with its <select>'s options.

.simpleselect("refreshState")

Update a SimpleSelect's state (disabled/enabled) according to the state of its <select>. (Contrarily to the two following methods, it doesn't change the state of the <select>.)

.simpleselect("disable")

Disable a <select> and its SimpleSelect.

Short for:

$("select")
    .prop("disabled", true)
    .simpleselect("refreshState");

.simpleselect("enable")

Enable a disabled <select> and its SimpleSelect.

Short for:

$("select")
    .prop("disabled", false)
    .simpleselect("refreshState");

.simpleselect("updatePresentationDependentVariables")

Update all variables a SimpleSelect stores for presentation purposes, such as its position and size. This method should be called whenever a SimpleSelect's CSS or position changes.

Note: This method should only be called on an inactive SimpleSelect (when its options list isn't visible).

SimpleSelect events

change

This event is fired on the original <select> when its value (thus the SimpleSelect's) is changed, exactly like the standard change event.

SimpleSelect appearance customization

jQuery.SimpleSelect comes with a default stylesheet. You can use it and modify it as much as you wish to make your SimpleSelects look exactly like you want.

Here's an overview of how a SimpleSelect works to make customizing it easier:

  1. For the sake of this example, let's say the plugin has been called on a very simple <select>, resulting in the following generated HTML.

    The HTML structure is straightforward: a .simpleselect container that holds two children, .placeholder and .options.

    <div class="simpleselect">
        <div class="placeholder">Option 1</div>
        <div class="options">
            <div class="option">Option 1</div>
            <div class="option">Option 2</div>
            <div class="option">Option 3</div>
        </div>
    </div>
    
  2. When the SimpleSelect is inactive, only the placeholder is visible inside the main container.

    Inactive SimpleSelect illustration

  3. When the SimpleSelect is active, the options list becomes visible and is placed inside the main container, in place of the placeholder.

    Active SimpleSelect illustration

    If the selected option isn't the first in the list, the options list is also pulled upward.

    Active SimpleSelect illustration #2

If you want to customize a SimpleSelect's appearance, it's important to remember that both the placeholder and the options list are displayed inside the same container. They should thus have similar look and dimension – so make sure they have the same margin, border, padding, font style…

Notes

  • jQuery.simpleselect works with jQuery 1.6 and above.

Warnings

  • jQuery.SimpleSelect uses the change event from the original <select> to work. To avoid conflicts, when the plugin is called on a <select>, it automatically removes any change event listener that has been previously attached to that <select>.

These are warnings about CSS-related edge cases you shouldn't run into very often (if at all):

  • If using a version of jQuery <1.8, setting the SimpleSelect's options list's box-sizing CSS property to something else than content-box and using vertical padding/borders will make the height of the options container behave oddly. So, just don't.
  • You can use padding and borders on the SimpleSelect and its children, but no margin. If you need a margin around the SimpleSelect's options list, the containerMargin option does just that.

Changelog

jQuery.SimpleSelect is now on version 2.x. More specifically, it means the plugin has, since its first version, been rewritten, and that some major, breaking changes have been introduced.

If upgrading from the first version of the plugin, you're highly advised to read the changelog below.

Click to view the changelog

Version 2.0.0 (2/26/2014)

  • The following methods have been added: .simpleselect("refreshState"), .simpleselect("refreshContents"), .simpleselect("updatePresentationDependentVariables")
  • The fadeSpeed option now defaults to 0. It's also been renamed to fadingDuration, but the old name still works.
  • The option containerMargin has been added.

Breaking changes

  • The first version of the plugin used to measure and compute a lot of things related to the SimpleSelect's position and size each time it was activated; this is not the case anymore. Although it has allowed to improve the plugin's performance, it also means that some issues may appear if you used to instantiate SimpleSelects and change the way they looked along the way. If changing the position or size of a SimpleSelect, you now have to call the method .simpleselect("updatePresentationDependentVariables") to make sure the plugin is made aware of these changes.
  • The following events have been removed: change.simpleselect, pressedEnter.simpleselect. Only the standard change event is now fired. The removal of change.simpleselect is not breaking though: namespaced events are also triggered by their unnamespaced counterparts (an event handler attached to change.simpleselect will still be executed when change is fired).
  • If you used other features than the documented ones in the first version, please note the plugin has been rewritten from scratch, so you'd better have a look at the new source code before upgrading.

Download on GitHub