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:

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.