select-mania
A jQuery select plugin.
Examples
Depencies
Quick start
Link the main CSS and JS files:
<link rel="stylesheet" href="path-to-select-mania/select-mania.css" /> <script type="text/javascript" src="path-to-select-mania/select-mania.js"></script>
Initialize select-mania:
$('target-selector').selectMania(); //OR $('target-selector').selectMania({ //settings });
Use select-mania methods:
$('target-selector').selectMania('method'); //OR $('target-selector').selectMania('method', { //settings });
Settings
ajax
Default: false
Select-mania can load items in ajax while scrolling, and do ajax search.
In order to enable ajax features, set the ajax
setting to a function like this:
function(search, page, data, callback) { //send back html options to select-mania callback(hmtlOptions); }
The function takes 4 arguments:
search
: the current search input valuepage
: the requested page numberdata
: provided custom data (see below)callback
: function to call to send back the result
The results sent by the callback function must be options to add / options found (if searching) in the form of a HTML string, or jQuery / DOM elements.
ajax: function(search, page, data, callback) { $.ajax({ type: 'POST', url: 'myAjaxScript.php', data: { search: search, page: page, custom: data.custom }, success: function(html) { callback(html); } }); }
data
Default: {}
This data will be set as argument in the ajax function if enabled.
empty
Default: false
If this setting is enabled, the select value will be forced as empty on initialization.
It can be useful in case of a non-multiple select with no placeholder so it doesn't display the first option value as default value.
Can be set by passing a data-empty
attribute on the select element.
hidden
Default: false
Set this setting to true if you want the select to be hidden at initialization.
placeholder
Default: 'Select an item'
The text of the placeholder.
In case of a non-multiple select, if a placeholder is set and no options are selected, the value will be forced as empty and the placeholder will be displayed.
Can be set by passing a data-placeholder
attribute on the select element.
removable
Default: false
Set this setting to true
to be able to remove the selected option of a simple select, even without any empty option available.
Can be set by passing a data-removable
attribute on the select element.
scrollContainer
Default: null
A selector or element which is the scrollable container of the select.
If a scroll container is set, the dropdown will be opened in a special way so it does not go under the scrollable element.
Note that the dropdown will close automatically if any scroll is detected on the scroll container.
search
Default: false
If set to true
, a search input will be available in the dropdown to search for items to select.
If the ajax
setting is enabled, the search will be made in ajax with the provided function (see below).
Can be set by passing a data-search
attribute on the select element.
size
Default: 'medium'
The size of the select.
Three sizes are available: 'tiny'
, 'small'
, 'medium'
, 'large'
Can be set by passing a data-size
attribute on the select element.
themes
Default: []
An array of the themes names to apply.
Themes CSS files can be found in the themes
folder with names like select-mania-theme-[themeName].css
You can create your own theme! A sample.css
theme file is here to help you doing that.
width
Default: '100%'
The select width.
Must be a valid CSS width.
Can be set by passing a data-width
attribute on the select element.
zIndex
Default: null
A z-index value for the dropdown.
Can be useful if the select is placed in a high z-index element so it doesn't go under it.
This option works only if scrollContainer
is enabled.
Option settings
disabled
Disabled option or optgroup elements will be render as disabled items or groups in the dropdown.
<optgroup label="Group" disabled> <option value="1" disabled>Item</option> </optgroup>
hidden
Options and group of options can be hidden by setting a data-hidden
attribute with true
as value. If the data-hidden
attribute value is changed, use the update
method to update options visibility.
<option value="1" data-hidden="true">One</option> <optgroup data-hidden="true"> <option value="2">Two</option> </optgroup>
icon
An icon can be placed before any item or group text. If a data-icon
attribute is set on an option or optgroup element, an i
icon element will be created with the data-icon
attribute value as class and will be placed before the element text. Therefore this feature is font-awesome friendly.
<optgroup data-icon="fa fa-user" label="Group"> <option value="1" data-icon="fa fa-user">Item</option> </optgroup>
optgroup
Optgroup elements are supported.
<optgroup label="Group"> <option value="1">Item</option> </optgroup>
selected
Any selected option element will be set as selected value, unless the empty
option is enabled.
<option value="1" selected>Item</option>
Setup settings
Settings can be set globally by using the selectManiaSetup
method.
The settings set that way will be apply by default on every select initialized with the plugin.
$.selectManiaSetup({ /* global settings */ });
Methods
check
This method can be called on a single element only!
Returns true
if select-mania is initialized on the targeted select, false
otherwise.
if($('target-selector').selectMania('check')) { // select-mania is initialized! }
clear
Clear the selected values of the targeted select.
$('target-selector').selectMania('clear');
close
Close the dropdowns of the targeted select elements.
$('target-selector').selectMania('close');
destroy
This method destroys select-mania on the targeted elements.
The select-mania element will be removed and the original select set to this original state.
$('target-selector').selectMania('destroy');
get
This method can be called on a single element only!
Call this method to get parsed selected values of a select-mania initialized element.
var values = $('target-selector').selectMania('get'); values: [ { value: '20', text: 'Value number twenty' }, { value: '60', text: 'Value number sixty' } ]
hide
This method hides select-mania.
$('target-selector').selectMania('hide');
init
Call this method to initialize select-mania on the targeted select elements.
//simple call $('target-selector').selectMania({/*settings*/}); //explicit call $('target-selector').selectMania('init', {/*settings*/});
open
Open the dropdowns of the targeted select elements.
$('target-selector').selectMania('open');
set
This method can be called on a single element only!
This method sets the provided values as selected values on the targeted select-mania initialized element.
This can be useful to set selected values on further initialization, if these values were selected from ajax scroll / search and are not there anymore.
The provided values must be formed like the data returned by the get
method.
$('target-selector').selectMania('set', [ { value: '20', text: 'Value number twenty' }, { value: '60', text: 'Value number sixty' } ]);
show
This method shows select-mania if it was hidden.
$('target-selector').selectMania('show');
update
Updates select-mania on targeted elements.
The select-mania element will be updated according to the original select options.
$('target-selector').selectMania('update');
Questions
How can I dynamically set the value of my select?
Simple! Set the value with $('#mySelect').val(value)
, then update selectMania with $('#mySelect').selectMania('update')
!
Can I still get the selected values directly from the original select element?
Of course! Just use $('mySelect').val();
. Any changes on the select-mania element is passed on the original select element.
Which attributes are supported?
Select-Mania supports the following attributes on the select element: disabled
, required
and multiple
.
I want to control this thing with my keyboard!
You're a keyboard person? Select-Mania can be manipulated with standard keyboard controls. Try it out!
Dude, this plugin doesn't work!
Oh... Sorry about that! Please feel free to post issues on the select-mania repository! I'll do my best to fix what's broken.