Gumi

Simple jQuery plugin for creating custom styled form select elements and dropdowns with CSS.

View project onGitHub

Overview / Demo

Gumi takes simple markup and maps it to a hidden select. This allows you to have sweet looking form select/options and also gives you the flexability to create simple dropdowns!

  • Please select
  • Option 1
  • Option 2
  • Option 3

Installation

Installing Gumi is relatively straight forward. Gumi depends on jQuery, so make sure you have that included on your page first. Once that's done, simply include both the Gumi library files (e.g. jquery.gumi.min.js and gumi.min.css) like so:


<link rel="stylesheet" type="text/css" href="/css/gumi.min.css"></link>
<script type="text/javascript" src="/js/jquery.gumi.min.js"></script>

HTML Structure

Once created, all of your dropdowns have a common HTML structure, like so:


<div class="gumi">
  <button>Please select an option</button>
  <ul>
    <li data-value="1">Option 1</li>
    <li data-value="2">Option 2</li>
    <li data-value="3">Option 3</li>
  </ul>
</div>

Notice the data-value attributes on the options? To give you some flexability, Gumi provides a simple and clean interface in order to handle customization of your dropdown straight from the markup. You can apply these attributes directly to the HTML tags themself. Most of the options are based on the native select conventions to keep things simple.

Data Attributes for the Button button
data-name Optional String value. This will name the select that is associated with your dropdown, giving you the flexibility of customizing the name of the select that get's submitted with your form.
data-class Optional String value. Gumi will apply this class to the hidden select that is associated with your dropdown, in case you ever want to write some custom code to hook into it.
data-required Optional Boolean value, defaults to false. Gumi will add the "required" attribute to the select that is associated with your dropdown.

Data Attributes for the Options li
data-value The value to be used for the form submit. If ommitted, Gumi will use the html string between the li tags
data-label String value. Defaults to the data-value. Sometimes you want the display label of the option to be different from the option value that gets submitted with your form. You can achieve this by setting a data-label on the option.
data-selected Boolean value. Defaults to the first option value in the list of options. When used, Gumi will recognize the first occurence of the data-selected attribute as the default selected option. This gives you the flexibility to pre-set the default value to any option you want.
data-disabled Boolean value. Default value is false. If the value is set to true, the option in the dropdown will be visible but won't be selectable.
data-selectable Boolean value. Default value is true. If the value is set to false, the option will not appear to the user as an option to select in the dropdown. This is generally used as the first item in the list of options to give the dropdown a unique call to action label (e.g. "Please Select An Option").

Simple Javascript Initialization

After you have the HTML written, now you can initialize the plugin:


<script type="text/javascript">
  $(function() {
    $('.gumi').gumi();
  });
</script>

Advanced Javascript Initialization

Gumi ships with a bunch of customizable options. You can do this by passing an object into the gumi() function as an argument. You can specify as many options as you'd like:


$('.gumi').gumi({
  buttonClass: 'btn btn-blue',
  onChange: function() {
    alert('You selected option: ' + this.val())
  }
});
Javascript Initization Options
buttonClass Optional String value. Default value is btn-default. This class will get applied to all of the button elements during initialization. You can apply multiple classes by separating each unique class with a space.
buttonSelectedClass Optional String value. Default value is btn-selected. Gumi applies this class to the option that is selected in the list of options dropdown.
optionDisabledClass Optional String value. Default value is option-disabled. All li elements that have the data-disabled="true" will have this class applied to them. This provides a way to style the disabled options looks and feel.
dropdownClass Optional String value. Default value is dropdown-default. Gumi will apply a unique class to your dropdown of options. All ul elements that wrap around the li options will have this class.
onChange Optional function callback. A change event fires when the user selects an option from the dropdown. This provides a simple way to hook into the change event and write your own custom functionality. Your callback will inherit the context of the drop down that is being interacted with. Hence, this in your function will refer to the hidden HTML select element that changed.
onOpen Optional function callback. When the user clicks on the button to display the list of options, Gumi fires a custom onOpen event to hook into. This event fires just before the options are displayed. Your callback will inherit the context of the drop down that is being interacted with. Hence, this in your function will refer to the hidden HTML selectthat changed.

Dealing with Gumi Programmatically through our API

Somtimes you have multiple instances of Gumi on your page and you want an easy way to hook into one to extend it with some unique behaviors.


<div class="gumi js-number-select">
  <button data-name="number">Please select a number</button>
  <ul>
    <li data-value="1">One</li>
    <li data-value="2">Two</li>
    <li data-value="3">Three</li>
  </ul>
</div>

<div class="gumi js-word-select">
  <button data-name="word">Please select word</button>
  <ul>
    <li data-value="gumi">Gumi</li>
    <li data-value="works">Works</li>
    <li data-value="great">Great</li>
  </ul>
</div>

Notice the extra class on each of the wrapping divs? They are both unique class identifiers, so we can specifically target one of them to enhance. Something custom may look like this:


  // First, initialize gumi for all of our dropdowns
  $('.gumi').gumi({
    dropDownClass: 'sweet-dropdown-wrap'
  });

  // By calling .data('gumi') on a node that already has gumi initialized on it,
  // you gain access to the Gumi public API methods for that particular node
  var numberSelect = $('.js-number-select').data('gumi');

  // Now that we have access to Gumi's public API (noted below) for this node,
  // let's customize it's interaction
  numberSelect.onEvent('onChange', function() {
    alert('Wow, you just selected a number!');
  });

  // And we can do the same thing for the other one!
  // Let's give the 'word selector' it's own little behavior as well
  var wordSelect = $('.js-word-select').data('gumi');

  wordSelect.onEvent('onOpen', function() {
    alert('Customization is key, please choose a word!');
  });

  wordSelect.onEvent('onChange', function() {
    alert('Nice, my favorite word!');
  });

Voila! Not to shabby right? There are a bunch of Public API methods that you can use to make your life dealing with gumi a little easier. These methods include:

Gumi Public API Methods
setSelected(value) Argument type(s): "value" string

Set the selected option based on it's value. If the option value does not exist, nothing will happen.
setSelectedOption(index) Argument type(s): "index" number

Set's the selected option for the current instance of Gumi based on the index of the option in the list of options
onEvent(event, callback) Argument type(s): "event" string, "callback" function
Events supported: onChange, onOpen

Binds custom function call backs to certain events.
closeDropdown() This method will close the current dropdown.
reset() This method will reset Gumi's selected state (and value) to the initial state during the initialization

Authors and Contributors

This plugin is written and maintained by Billy Bastardi (@b1lly).

Support or Contact

Having trouble with Gumi? Maybe your problem has already been solved! Check out the known issues at https://github.com/b1lly/gumi/issues. If not, feel free to file a new issue.