Minimal jQuery Html Select Replacement Plugin - Selectric

File Size: 398 KB
Views Total: 11677
Last Update:
Publish Date:
Official Website: Go to website
License: MIT
   
Minimal jQuery Html Select Replacement Plugin - Selectric

Selectric is an ultra-light jQuery based alternative to the default Html select element that supports keyboard navigation, callback events and customization.

Installation:

# NPM
$ npm install selectric --save

Basic Usage:

1. Include the latest jQuery javascript library and jQuery Selectric Plugin in your web page

<script src="http://code.jquery.com/jquery-latest.min.js"></script>
<script src="js/jquery.selectric.js"></script> 

2. Include the default theme CSS in your page. You can easily customize your html list in this CSS file.

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

3. Create a standard html select

<select id="fruits">
<option value="0">Select with few options</option>
<option value="apple">Apple</option>
<option value="banana">Banana</option>
</select>

4. Call the plugin with options.

$('select').selectric({

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

  /*
  * 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: '&lt;b class=&quot;button&quot;&gt;&amp;#x25be;&lt;/b&gt;',

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

  /*
   * Type: Boolean
   * Description: Retain native dropdown behavior on mobile devices
   */
  nativeOnMobile: true,

  /*
  * Type: Boolean
  * Description: Open select box on focus, instead of click
  */
  openOnFocus: 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,

  forceRenderAbove: false,
  forceRenderBelow: false,
  stopPropagation: true,

  /*
  * 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: pluginName,
    camelCase: false
  },

  /*
  * Type: String or Function
  * Description: Define how each option should be rendered inside its &lt;li&gt; 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}',

  listBuilder: false,  

  /*
  * 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,

  /*
   * Type: Object
   * Description: Customize select "multiple" behavior
   */
  multiple: {
    separator: ', ',
    keepMenuOpen: true,
    maxLabelEntries: false
  }

});

Change logs:

2018-03-16

  • Changed label and button classes to avoid conflicts. Changed/added some Sass variables, some small optmizations on the CSS

v1.13.0 (2017-08-23)

  • Add forceRenderBelow option
  • Bugfixed.

v1.11.2 (2017-05-11)

  • re-apply missing callback arguments

v1.11.1 (2017-01-11)

  • Fix disabled for optgroup options
  • Fix empty label

v1.11.0 (2016-10-07)

  • Fix conflict
  • Accessibility improvement
  • Removed `hooks` reference and update plugins to use events.
  • Add basic support for multiple selects
  • Fixed an issue where you could click on optgroup label and break the plugin

v1.10.1 (2016-09-23)

  • Change label markup to avoid conflicts
  • add basic support for multiple selects
  • Accessibility improvements
  • allow hook chaining
  • Trigger the onChange event only when the value has changed
  • fixed Word search doesn't work on dynamicaly created optionlists

v1.9.6. (2016-03-28)

  • Fixed: Only render selectric-items at top, if they fit in the viewport

v1.9.6. (2016-03-24)

  • Fixed: Only render selectric-items at top, if they fit in the viewport

v1.9.5. (2016-02-27)

  • Added missing dash between prefix and class name
  • UMD support

v1.9.3 (2015-06-03)

  • Fixed camelCase in custom themes

v1.9.2 (2015-04-07)

  • Added option labelBuilder

v1.9.0 (2015-03-18)

  • Added <optgroup> support

v1.8.7 (2015-01-15)

  • fixed bugs.

v1.8.5 (2014-09-24)

  • fixed bump version in build process

v1.8.4 (2014-09-24)

  • Fixed: hover effect still not work properly

v1.8.3 (2014-09-01)

  • Fixed: Open selectbox bug on page with several selectbox

v1.8.1 (2014-09-01)

  • Added tabindex support

v1.8.0 (2014-08-29)

  • Added some callbacks, added a new div inside options box for better control, updated CSS

v1.7.3 (2014-08-26)

  • Added onRefresh option and inheritOriginalWidth option

v1.7.2 (2014-08-18)

  • Fix some key press behaviors

v1.7.1 (2014-07-29)

  • Added classes for options box positioning

v1.6.8 (2014-06-28)

  • Complete plugin code re-organization
  • Added option preventWindowScroll
  • Fix keyboard showing on mobile

v1.6.8 (2014-05-14)

  • Improved code quality

v1.6.7 (2014-05-03)

  • Added option to customize items box markup, fix for expandToItemText

v1.6.6 (2014-04-05)

  • Bugs fixed.

v1.6.4 (2014-02-27)

  • Fix dummy input not being removed upon destroy

v1.6.3 (2014-02-27)

  • bugx fixed.

v1.6.2 (2014-02-25)

  • Fix replace diacritics regular expression

v1.6.1 (2014-02-13)

  • bug fixed
  • optmized selectors order in CSS

v1.6.0 (2014-02-08)

  • Various bug fixes and changes; added a SCSS version;
  • Now works on any element, not just select

v1.5.9 (2014-01-17)

  • Fix keyboard navigation
  • Fix various bugs

v1.5.7 (2014-01-09)

  • Fixed: callback functions should provide the refrence object for the select element

v1.5.6 (2014-01-08)

  • Fixed: The change event is not available in the select-tag if the select tag options have same display texts

v1.5.5 (2013-12-12)

  • Fixed Expand long text items past wrapper.
  • Fixed Disabled items.

v1.5.4 (2013-12-04)

  • Fixed TAB key handling (focus, blur) and added option to open select box on hover

This awesome jQuery plugin is developed by lcdsantos. For more Advanced Usages, please check the demo page or visit the official website.