iskrid / jquery-selectric

jQuery plugin for easy manipulation and customization of HTML selects

#jQuery Selectric

jQuery Selectric is a jQuery plugin designed to help at stylizing and manipulating HTML selects.

• Keyboard navigation (Up/Down/Left/Right/Word search)
• Easily customizable
• Pretty lightweight
• Options box always stay visible
• Doesn't rely on external libraries (besides jQuery)
• Word search works with western latin characters set (e.g.: á, ñ, ç...)

###Demo

##How to use:

Make sure to include jQuery in your page:

<script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js"></script>

Include jQuery Selectric:

<script src="js/jquery.selectric.min.js"></script>

Include jQuery Selectric styles, and change it to your taste :D (please refer to our demo page for more themes and other customizations)

<link rel="stylesheet" href="selectric.css">

Initialize jQuery Selectric:

<script>
$(function(){
  $('select').selectric();
});
</script>

##Options:

You can pass an options object as the first parameter when you call the plugin. For example:

$('select').selectric({
  maxHeight: 200
});

{
  /*
   * Type: Function
   * Description: Function called before plugin initialize
   */
  onBeforeInit: function() {},

  /*
   * Type: Function
   * Description: Function called plugin has been fully initialized
   */
  onInit: function() {},

  /*
   * Type: Function
   * Description: Function called plugin has been fully initialized
   */
  onBeforeOpen: function() {},

  /*
   * Type: Function
   * Description: Function called after select options opens
   */
  onOpen: function() {},

  /*
   * Type: Function
   * Description: Function called before select options closes
   */
  onBeforeClose: function() {},

  /*
   * Type: Function
   * Description: Function called after select options closes
   */
  onClose: function() {},

  /*
   * Type: Function
   * Description: Function called before select options change
   */
  onBeforeChange: function() {},

  /*
   * Type: Function
   * Description: Function called when select options change
   */
  onChange: function(element) {
    $(element).change();
  },

  /*
   * Type: Function
   * Description: Function called when the Selectric is refreshed
   */
  onRefresh: function() {},

  /*
   * Type: Integer
   * Description: Maximum height options box can be
   */
  maxHeight: 300,

  /*
   * Type: Integer
   * Description: After this time without pressing
   *              any key, the search string is reset
   */
  keySearchTimeout: 500,

  /*
   * Type: String [HTML]
   * Description: Markup for open options button
   */
  arrowButtonMarkup: '<b class="button">▾</b>',

  /*
   * Type: Boolean
   * Description: Initialize plugin on mobile browsers
   */
  disableOnMobile: true,

  /*
   * Type: Boolean
   * Description: Open select box on hover, instead of click
   */
  openOnHover: false,

  /*
   * Type: Integer
   * Description: Timeout to close options box after mouse leave plugin area
   */
  hoverIntentTimeout: 500,

  /*
   * Type: Boolean
   * Description: Expand options box past wrapper
   */
  expandToItemText: false,

  /*
   * Type: Boolean
   * Description: The select element become responsive
   */
  responsive: false,

  /*
   * Type: Object
   * Description: Customize classes.
   *              Every class in 'postfixes' should be separate with a
   *              space and follow this exact order:
   *              'Input Items Open Disabled TempShow HideSelect Wrapper
   *              Hover Responsive Above Scroll Group GroupLabel'
   */
  customClass: {
    prefix: 'selectric',
    camelCase: false,
    overwrite: true
  },

  /*
   * Type: String or Function
   * Description: Define how each option should be rendered inside its <li> element.
   *
   *              If it's a string, all keys wrapped in brackets will be replaced by
   *              the respective values in itemData. Available keys are:
   *              'value', 'text', 'slug', 'disabled'.
   *
   *              If it's a function, it will be called with the following parameters:
   *              (itemData, element, index). The function must return a string,
   *              no keys will be replaced in this method.
   */
  optionsItemBuilder: '{text}',

  /*
   * Type: String or Function
   * Description: Define how each select label should be rendered. Allows HTML.
   *
   *              If it's a string, all keys wrapped in brackets will be replaced by
   *              the respective values in currItem. Available keys are:
   *              'value', 'text', 'slug', 'disabled'.
   *
   *              If it's a function, it will be called with the following parameters:
   *              (currItem). The function must return a string, no keys will be
   *              replaced in this method.
   */
  labelBuilder: '{text}',

  /*
   * Type: Boolean
   * Description: Prevent scroll on window when using mouse wheel inside options box
   *              to match common browsers behavior.
   */
  preventWindowScroll: true,

  /*
   * Type: Boolean
   * Description: Inherit width from original element
   */
  inheritOriginalWidth: false,

  /*
   * Type: Boolean
   * Description: Determine if current selected option should jump to
   *              first (or last) once reach the end (or start) item of list upon
   *              keyboard arrow navigation.
   */
  allowWrap: false
}

##Events:

All events are called on original element, first argument is the original element too. And can be bound like this:

$('select').on('eventname', function(element){
  // your code
});

eventname can be one of the following:

Event name	Description
selectric-before-init	Fired before plugin initialize
selectric-init	Fired plugin has been fully initialized
selectric-before-open	Fired before select options opens
selectric-open	Fired after select options opens
selectric-before-close	Fired before select options closes
selectric-close	Fired after select options closes
selectric-before-change	Fired before select options change
selectric-change	Fired when select options change
selectric-refresh	Fired when the Selectric is refreshed

##Hooks:

Check jquery.selectric.placeholder.js source for a usage example

// Add a callback everytime 'callbackName' is called
$.fn.selectric.hooks.add('callbackName', 'hookName', function(element, data) {});

// Remove a callback
$.fn.selectric.hooks.remove('callbackName', 'hookName');

##Public methods:

var Selectric = $('select').data('selectric');

Selectric.open();    // Open options
Selectric.close();   // Close options
Selectric.destroy(); // Destroy select and go back to normal
Selectric.refresh(); // Reconstruct the plugin options box
Selectric.init();    // Reinitialize the plugin

// Or...
$('select').selectric('open');    // Open options
$('select').selectric('close');   // Close options
$('select').selectric('destroy'); // Destroy select and go back to normal
$('select').selectric('refresh'); // Reconstruct the plugin options box
$('select').selectric('init');    // Reinitialize the plugin

##Browser support:

• Firefox
• Chrome
• Safari
• Internet Explorer 7+
• Opera