mForm Documentation
Replace your browsers default select field with a more awesome one.
Setup
In addition to MooTools and MooTools More/Element.Measure you need to include following files:
- mForm.Core.js
- mForm.Element.js
- mForm.Element.Select.js
- assets/mFormElementSelect.css
Replace a select field
Now simply add the attribute data-select to your select fields to replace them with the custom one:
<select data-select> <option value="1">First option</option> <option value="2">Second option</option> </select>
To customize your select field, you can set your options in the attributes value:
<select data-select="{max: 5, maxBuffer: 2}">
Alternatively you can also create a new instance of mForm.Element.Select:
new mForm.Element.Select({ original: 'mySelectField' // See section options for more info });
<select id="mySelectField"> … </select>
Search your options
Your custom select fields have a search field by default. It will only show if there are more than 20 options.
You can change the amount of options, when the search field should be shown:
<select data-select="{search: 10}"> … </select>
Set search to true to always display the search field, or false to disable searching.
Add a placeholder
The HTML5 attribute placeholder also adds a placeholder to your custom select fields:
<select data-select placeholder="Please select something"> … </select>
If the first option in your select field has an empty value, it will be used as placeholder:
<select data-select> <option value="">This is my placeholder</option> <option value="1">First option</option> <option value="2">Second option</option> </select>
Deselect an option
By default you can deselect the selected option if there is a placeholder to show instead.
To disallow this, simply set removeSelected to false.
<select data-select="{removeSelected: false}"> <option value="">Try to deselect an option</option> <option value="1">First option</option> <option value="2">Second option</option> </select>
Group your options
Wrap your options in an optgroup to group them:
<select data-select> <optgroup label="First group"> <option value="1">First option</option> <option value="2">Second option</option> </optgroup> <optgroup label="Second group"> <option value="3">Third option</option> <option value="4">Fourth option</option> </optgroup> </select>
Your optgroups are open by default. Use data-optgroup-closed to have an optgroup closed by default.
<select data-select> <optgroup label="This group id closed" data-optgroup-closed> <option value="1">First option</option> <option value="2">Second option</option> </optgroup> <optgroup label="This group is open"> <option value="3">Third option</option> <option value="4">Fourth option</option> </optgroup> </select>
Style your options
You can use class and style to style your options:
<style type="text/css"> .country span { background-position: 10px 5px; background-repeat: no-repeat; text-indent: 28px; } .country_US span { background-image:url('US.png'); } .country_NL span { background-image:url('NL.png'); } .country_DE span { background-image:url('DE.png'); } .color span { color: inherit !important; } </style>
<select data-select> <optgroup label="Countries"> <option value="us" class="country country_US">United Stated</option> <option value="nl" class="country country_NL">Netherlands</option> <option value="de" class="country country_DE">Germany</option> </optgroup> <optgroup label="Colors"> <option value="red" class="color" style="color:red">Red</option> <option value="green" class="color" style="color:green">Green</option> <option value="blue" class="color" style="color:blue">Blue</option> </optgroup> </select>
Notice that styles should be applied to span, as this is the last element in the option.
Options
This is the complete list of options you can set for mForm.Element.Select:
original: null, |
The element id or element reference of the select field to replace. |
placeholder: '', |
The default placeholder of your select field. |
placeholderSearch:
'Search...', |
The default placeholder of the search field. |
noSearchResults:
'No options found...', |
The notice when no search results have been found. |
noOptions:
'There are no options...', |
The notice when there are no options to select. |
search: 20, |
This many options are neccessary for the search field to appear. Set to true to always display the search field, or false to disable the search. |
max: 20, |
The maximum amount of options to be shown, others will show when scrolling. |
maxBuffer: 3, |
Only if max + maxBuffer > options, the options will be hidden and scrolling will be enabled |
focusSearch: false, |
Automatically sets the focus to the search field when opening the options. |
position: 'bottom', |
The position of the options container. Can be 'top' to fade the container on top of the select field or 'bottom' to use the dropdown effect. |
tween: 'height', |
Can be 'opacity' (fade effect) or 'height' (dropdown effect, works only if position == 'bottom'). |
autoPosition: true, |
Adjusts the position of the options container if there is not enough space availible to show all options. |
windowOffset: 10, |
Minimal distance of the options container to the window edges. |
scrollSpeed: 100, |
Scrolling duration for one option. |
scrollFast: 30, |
Scrolling duration for one option when scrolling fast, e.g. klicking on down or up button. |
scrollWheelSpeed: 30, |
Scrolling duration for one option when using the mouse wheel. |
scrollWheelStep: 3, |
This many options will be scrolled with one scroll wheel step. |
dropdownDuration: 250, |
How fast the options menu drops down or tweens back. |
fadeDuration: 250, |
How fast the options menu fades when it is opened on top of select field. |
removeSelected: true, |
Set to false to disallow deselecting an option. |
zIndex: 2000, |
The zIndex of the select field. It should be high to make sure it will be above all your other absolute positioned elements. |