jQuery.SimpleSelect, make every <select> fully customizable
jQuery.SimpleSelect replaces every
<select> with a HTML + CSS alternative. The result is 100% stylable selects.
Other live examples
- Using the plugin's options
- Disabling an re-enabling the SimpleSelect
- Updating the select's options on the fly, and updating the SimpleSelect accordingly
- Watching the
A SimpleSelect behaves the same way a
- 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
- 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
- Handle the
disabledattribute on an
<select> <option>Option 1</option> <option>Option 2</option> <option>Option 3</option> </select>
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
idattribute, the generated SimpleSelect will have the same
id, prepended with
<select>on which the plugin has been called has the class
.simpleselected, and is hidden inside a
<div>with the class
<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.
fadingDuration (number, default:
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:
Margin left between the options list and the window's edges when the SimpleSelect is active (in pixels).
displayContainerInside (string, default:
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.
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.
Set a SimpleSelect in an active state (show its options list).
Set a SimpleSelect in an inactive state (hide its options list).
Re-populate a SimpleSelect's with its
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> and its SimpleSelect.
$("select") .prop("disabled", true) .simpleselect("refreshState");
Enable a disabled
<select> and its SimpleSelect.
$("select") .prop("disabled", false) .simpleselect("refreshState");
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).
This event is fired on the original
<select> when its value (thus the SimpleSelect's) is changed, exactly like the standard
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:
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
.simpleselectcontainer that holds two children,
<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>
When the SimpleSelect is inactive, only the placeholder is visible inside the main container.
When the SimpleSelect is active, the options list becomes visible and is placed inside the main container, in place of the placeholder.
If the selected option isn't the first in the list, the options list is also pulled upward.
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…
- jQuery.simpleselect works with jQuery 1.6 and above.
- jQuery.SimpleSelect uses the
changeevent from the original
<select>to work. To avoid conflicts, when the plugin is called on a
<select>, it automatically removes any
changeevent listener that has been previously attached to that
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-sizingCSS property to something else than
content-boxand 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
containerMarginoption does just that.
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.
Version 2.0.0 (2/26/2014)
- The following methods have been added:
fadeSpeedoption now defaults to
0. It's also been renamed to
fadingDuration, but the old name still works.
- The option
containerMarginhas been added.
- 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:
pressedEnter.simpleselect. Only the standard
changeevent is now fired. The removal of
change.simpleselectis not breaking though: namespaced events are also triggered by their unnamespaced counterparts (an event handler attached to
change.simpleselectwill still be executed when
- 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.