Boost JS Select Menu

A style-free and accessible select menu plugin for jQuery and Boost JS. While other plugins style your select menu for you, this plugin only handles the functionality, leaving the layout and styling up to you.

Installation

Install with npm:

npm install boost-js-select

Install in browser:

<script src="https://cdn.rawgit.com/marksmccann/boost-js-select/v0.0.3/dist/select.min.js"></script>

Usage

Create Plugin

var boost = require('boost-js');
// var boost = $.fn.boost; (browser install)

var select = require('boost-js-select');
// var select = $.fn.boost.select; (browser install)

$.fn.select = boost( select.plugin, select.defaults );

Markup Structure

<label for="select">...</label>
<select id="select">
    <option>1</option>
    <option>2</option>
    <option>3</option>
</select>

Instantiate Plugin

$('#select').select();

Options

Name | Default | Description --- | --- | --- activeClass1 | "is-active" | the class added to option in menu that is highlighted openClass1 | "is-open" | the class added to menu when it is visible selectedClass1 | "is-selected" | the class added to option that is selected primaryClass1 | "select" | a string used to create classes for the markup structure. disabledClass1 | "is-disabled" | the class added to select when disabled matchWidth | false | will set the width of the menu equal to the select onOpen | null | a callback function called after the menu is made visible onClose | null | a callback function called after the menu is hidden onChange | null | a callback function called after a selection is made onInit | null | a callback function called after the select is initialized 1. See the "Class Placement" section below for a guide on where these classes are placed on the rendered markup.

Usage

$('#tooltip').tooltip({
    onInit: function() {
        console.log( this.id ); // 'select'
    }
});

- or -

<select id="select" data-match-width="true">...</select>

Class Placement

<span class="[primaryClass] [disabledClass]">...</span>
<ul class="[primaryClass]-menu [openClass]">
    <li class="[primaryClass]-option [activeClass] [selectedClass]"></li>
</ul>

API

open( fn )

Opens the option menu. fn: optional callback function called after opening.

instance.open();

close( fn )

Closes the option menu. fn: optional callback function called after closing.

instance.close();

isOpen()

Determines if them menu is open and visible or not. Returns boolean.

instance.isOpen(); // false

toggle( fn )

Closes the menu if it is open and vice versa. fn: optional callback function.

instance.toggle();

setPosition()

Calculates the sets the top/left position for the menu relative to the bottom left-hand corner of the select.

instance.setPosition();

disable()

Disables the select.

instance.disable();

enable()

Enables a disabled select.

instance.enable();

findOption( char )

Compares the first character of each option's html content against the character passed in and returns the index of the first match. Will return index of active option if no match is found.

instance.findOption( 'a' );

prevOption()

Returns the index of the previous option relative to the active one.

instance.prevOption();

nextOption()

Returns the index of the next option relative to the active one.

instance.nextOption();

activeOption()

Retrieves the index of the active/highlighted option.

instance.activeOption();

selectedOption()

Retrieves the index of the of the selected option.

instance.selectedOption();

activeTo( int )

Updates the active/highlighted option to the index passed in.

instance.activeTo( 1 );

changeTo( int, fn )

Updates the selected option to the index passed in. fn: optional callback function called after change. Will also trigger any change events assigned to the original select element.

instance.changeTo( 1 );

select

The new, customizable "select" element.

instance.select;

menu

The new, customizable dropdown menu element for the select.

instance.menu;

options

The set of new, customizable "option" elements that are direct descendants of the menu.

instance.options;

label

The label associated with the select.

instance.label;

disabled

A boolean value which store the disabled state of the select.

instance.disabled; // false

Running Tests

$ npm install && npm test

License

Copyright © 2016, Mark McCann. Released under the MIT license.