API-docs.md

Table of Contents

• • Dropkick
• Getting started
  • • disabled
    • form
    • length
    • multiple
    • options
    • selectedIndex
    • selectedOptions
    • value
    • add
    • item
    • remove
    • close
    • open
    • disable
    • hide
    • select
    • selectOne
    • search
    • focus
    • reset
    • refresh
    • dispose
  • initialize
  • mobile
  • change
  • open
  • close
  • search
  • bubble

Dropkick

Getting started

After you've cloned the repo you will need to add the library to your page. In the build/js folder use one of the two DropKick files given. One has a version number in the file name and the other is a version number-less version. You will also need to grab the css from build/css and load it on the page.

Once those files are imported into the page you can call DropKick on any HTMLSelectElement: new Dropkick( HTMLSelectElement, Options ); or new Dropkick( "ID", Options );. This returns the dropkick object to you. It may be useful for you to store this in a var to reference later.

If you're using jQuery you can do this instead: $('#select').dropkick( Options );

Parameters

• select
• options opts See list of properties you can pass in here
• sel elem HTMLSelect Element being passed.

Examples

// Pure JS
var select = new Dropkick("#select");

// jQuery
$("#select").dropkick();

Returns object DropKick Object for that select. You can call your methods on this if stored in a var

disabled

Whether the form is currently disabled or not

Properties

• disabled boolean

Examples

var select = new Dropkick("#select");

select.disabled;

form

The form associated with the select

Properties

• form node

Examples

var select = new Dropkick("#select");

select.form;

length

The number of options in the select

Properties

• length integer

Examples

var select = new Dropkick("#select");

select.length;

multiple

If this select is a multi-select

Properties

• multiple boolean

Examples

var select = new Dropkick("#select");

select.multiple;

options

An array of Dropkick options

Properties

• options array

Examples

var select = new Dropkick("#select");

select.options;

selectedIndex

An index of the first selected option

Properties

• selectedIndex integer

Examples

var select = new Dropkick("#select");

select.selectedIndex;

selectedOptions

An array of selected Dropkick options

Properties

• selectedOptions array

Examples

var select = new Dropkick("#select");

select.selectedOptions;

value

The current value of the select

Properties

• value string

Examples

var select = new Dropkick("#select");

select.value;

add

Adds an element to the select. This option will not only add it to the original select, but create a Dropkick option and add it to the Dropkick select.

Parameters

• elem string HTMLOptionElement
• before Node/Integer HTMLOptionElement/Index of Element

Examples

var select = new Dropkick("#select");

select.add("New option", 5);

item

Selects an option in the list at the desired index (negative numbers select from the end).

Parameters

• index Integer Index of element (positive or negative)

Examples

var select = new Dropkick("#select");

select.item(4); //returns DOM node of index

Returns Node The DK option from the list, or null if not found

remove

Removes the option (from both the select and Dropkick) at the given index.

Parameters

• index Integer Index of element (positive or negative)

Examples

var select = new Dropkick("#select");

select.remove(4);

close

Closes the DK dropdown

Examples

var select = new Dropkick("#select");

select.close(); //closes dk dropdown

open

Opens the DK dropdown

Examples

var select = new Dropkick("#select");

select.open(); //Opens the dk dropdown

disable

Disables or enables an option; if only a boolean is passed (or nothing), then the entire Dropkick will be disabled or enabled.

Parameters

• elem Integer The element or index to disable
• disabled Boolean Value of disabled

Examples

var select = new Dropkick("#select");

// To disable the entire select
select.disable();

// To disable just an option with an index
select.disable(4, true);

// To re-enable the entire select
select.disable(false);

// To re-enable just an option with an index
select.disable(4, false);

hide

Hides or shows an option.

Parameters

• elem Integer The element or index to hide
• hidden Boolean Whether or not to hide the element

Examples

var select = new Dropkick("#select");

// To hide an option with an index
select.hide(4, true);

// To make an option visible with an index
select.hide(4, false);

select

Selects an option from the list

Parameters

• elem String The element, index, or value to select
• disabled Boolean Selects disabled options

Examples

var elm = new Dropkick("#select");

// Select by index
elm.select(4); //selects & returns 5th item in the list

// Select by value
elm.select("AL"); // selects & returns option with the value "AL"

Returns Node The selected element

selectOne

Selects a single option from the list and scrolls to it (if the select is open or on multi-selects). Useful for selecting an option after a search by the user. Important to note: this doesn't close the dropdown when selecting. It keeps the dropdown open and scrolls to proper position.

Parameters

• elem Integer The element or index to select
• disabled Boolean Selects disabled options

Examples

var select = new Dropkick("#select");

select.selectOne(4);

Returns Node The selected element

search

Finds all options who's text matches a pattern (strict, partial, or fuzzy)

"strict" - The search string matches exactly from the beginning of the option's text value (case insensitive).

"partial" - The search string matches part of the option's text value (case insensitive).

"fuzzy" - The search string matches the characters in the given order (not exclusively). The strongest match is selected first. (case insensitive).

Parameters

• pattern
• mode Integer How to search; "strict", "partial", or "fuzzy"
• string String The string to search for

Returns Boolean An Array of matched elements

focus

Brings focus to the proper DK element

Examples

var select = new Dropkick("#select");

$("#some_elm").on("click", function() {
  select.focus();
});

reset

Resets the Dropkick and select to it's original selected options; if clear is true, It will select the first option by default (or no options for multi-selects).

Parameters

• clear Boolean Defaults to first option if true

Examples

var select = new Dropkick("#select");

// Reset to originally `selected` option
select.reset();

// Reset to first option in select
select.reset(true);

refresh

Rebuilds the DK Object (use if HTMLSelectElement has changed)

Examples

var select = new Dropkick("#select");

//... [change original select] ...

select.refresh();

dispose

Removes the DK Object from the cache and the element from the DOM

Examples

var select = new Dropkick("#select");

select.dispose();

initialize

Called once after the DK element is inserted into the DOM. The value of this is the Dropkick object itself.

mobile

Whether or not you would like Dropkick to render on mobile devices.

Properties

• mobile boolean

change

Called whenever the value of the Dropkick select changes (by user action or through the API). The value of this is the Dropkick object itself.

open

Called whenever the Dropkick select is opened. The value of this is the Dropkick object itself.

close

Called whenever the Dropkick select is closed. The value of this is the Dropkick object itself.

search

"strict" - The search string matches exactly from the beginning of the option's text value (case insensitive).

"partial" - The search string matches part of the option's text value (case insensitive).

"fuzzy" - The search string matches the characters in the given order (not exclusively). The strongest match is selected first. (case insensitive).

bubble

Bubble up the custom change event attached to Dropkick to the original element (select).