Dependencies

NameFile
Core/dist/js/core.js

Assets

TypeFile
jsdist/js/selectmenu.js
cssdist/css/selectmenu.css
lessdist/less/selectmenu.less
scssdist/scss/selectmenu.scss

Examples

Single Select

Bare bones select menu setup. Selectmenu defaults to a single select and the label value is the currently selected option.

Multi Select

Add the multiple attribute to turn select menus into multiselectable comboboxes. Multiselects are recommended to be given a label via the aria-label attribute.

Single Select W/ Optgroups

Selectmenu supports optgroups as well. With single selects, optgroups are not part of the keyboard or active indexing and are presentation elements for screen readers.

Multi Select W/ Optgroups

Multiselect menus with optgroups provide the user with the ability to select the optgroup. Selecting the optgroup will activate/deactivate all child options within the optgroup.

Selectmenu W/ Classnames

You can customize individual options, optgroups, and the root select node by adding classnames to your setup elements. Selectmenu will copy those classnames and add them to the renered ui elements.

Selectmenu W/ Clear All

Selectmenu comes with the opt-in ability for a Clear All option (text can be changed through format options). To consume this behavior simply add a data-removable="true" to your setup select element. Clear all only works with multiselects, since single selects always have a default value.

Selectmenu W/ Alt Text

You can also provide options with alternative text or a more detailed description. Add a data-alt="<your text here>" to create alt labelling.

Selectmenu W/ Restricted Height

If the height of your menu needs to be restricted to a perticular height, Selectmenu also supports scrolling through lists and keeping active/selected elements in view.

Setup

To setup a selectmenu, all you need is a root element and a native select. See the Examples Section below for details on the different options available through html data-attributes.

<div class="mk-sm-root">
	<select class="mk-sm" aria-label="My Options">
		<option value="1">Option One</option>
	</select>
</div>

Instantiation

Instantiating an instance of Selectmenu is easy. Just target the root element and pass in your config options if necessary. Config options are opt-in and most can be set as html data-attributes on the native select element making it easy to customize instances without passing in a config object. But in case you want to, below are all possible options available to pass in. Additionally, check out the Events Section for adding events to your instance.

var Selectmenu = Mk.get('Selectmenu');
//
// instantiate
var mySelect = new Selectmenu('.mk-sm-root', {
	multiple: true/false,
	removable: true/false,
	formats: {
		//change any of the formats for this instance only
	},
	templates: {
		//change any of the templates for this instance only
	}
});

Events

All events are part of the Mk EventEmitter and *not* added to the DOM. Events are also called in context of the component instance so it isn't a great idea to use a proxy function to change context, as you'll loose a lot of beneficial object access.

change

Fires when selectmenu value changes.


instance.on('change', function () {
	console.info(this.value);
});

show

Fired when menu is shown.


instance.on('show', function () {
	console.info('Menu has opened!');
});

hide

Fired when menu is hidden.


instance.on('hide', function () {
	console.info('Menu has closed!');
});

activate

Fired when an option becomes active.


instance.on('activate', function (option, keyboard) {
	console.info('active option:', option);
	console.info('came from keyboard (vs mouse):', keyboard);
});

disabled

Fired when selectmenu is disabled, if previously enabled.


instance.on('disabled', function () {
	console.info('Selectmenu has been diabled.');
});

enabled

Fired when selectmenu is enabled, if previously disabled.


instance.on('enabled', function () {
	console.info('Selectmenu has become enabled.');
});

update

Fired when updates are made to the rendered UI through the use of update().


instance.on('update', function () {
	console.info('Changes to the native select have been applied to the UI.');
});

API

Below are the different public properties and methods accessible to you, the end developer. All of these are accessible on your Selectmenu [sm] instance as well as inside event handlers bound to your instance. Some methods have intentionally been left out due to their difficulty tof use for end developers vs. internal use.

Methods

  • instance.unmount()

    Teardown component, remove from DOM, and free event, data, and reference memory.

    • No params required.

  • instance.move([up])

    Move the active selectmenu list item by one.

    Parameters
    • Name
      up
      Type
      Boolean
      Description
      Set as true to move up the list. Default is false.

  • instance.index(n)

    Get the index of an individual list option.

    Parameters
    • Name
      key
      Type
      Node
      Description
      Option in the selectmenu list UI.

  • instance.getOptgroupValue(optgroup)

    Get a generated value for an optgroup, representing the child option elements.

    Parameters
    • Name
      optgroup
      Type
      Node
      Description
      Optgroup Elment.

  • instance.getElementsByValue(value)

    Get the native option AND UI option element by searching the value.

    Parameters
    • Name
      value
      Type
      String
      Description
      Value of an option.

  • instance.getOptionByValue(value)

    Get the native option by searching the value.

    Parameters
    • Name
      value
      Type
      String
      Description
      Value of an option.

  • instance.updateLabel(n)

    Updates the label (trigger input value).

    Parameters
    • Name
      n
      Type
      Mixed - String/Node/undefined
      Description
      Pass as string to set select label as the string. Pass as node to parse the label from element. Leave empty to automatically update the label.

  • instance.label(n)

    Pareses a label (trigger input value) and returns it.

    Parameters
    • Name
      n
      Type
      Mixed - Node/undefined
      Description
      Pass as node to parse and return the label from element. Leave empty to return the current label..

  • instance.data()

    Generate a JSON representation of the selectmenu.

    • No params required.

  • instance.scrollTo(n)

    Scroll a selectmenu list with a restructed height to a perticular list item.

    Parameters
    • Name
      n
      Type
      Node
      Description
      An element in the selectmenu list to scroll to.

  • instance.show()

    Opens the list associated with the selectmenu.

    • No params required.

  • instance.hide()

    Closes the list associated with the selectmenu.

    • No params required.

  • instance.toggle()

    Toggles between open() and show()

    • No params required.

  • instance.activate(n[, keyboard])

    Set an active element in the selectmenu list.

    Parameters
    • Name
      n
      Type
      Node
      Description
      A Node reference from the list of selectmenu items.
    • Name
      keyboard
      Type
      Boolean
      Description
      Pass true for additional functionality (like updating the label), as keyboard interactivity applies different behavior.

  • instance.deselect(value[, silent])

    Deselects item(s) in the selectmenu.

    Parameters
    • Name
      value
      Type
      String
      Description
      An option value or combination of option values joined with "|||".
    • Name
      silent
      Type
      Boolean
      Description
      Pass in as true to prevent the change event from emitting. Default value is false.

  • instance.deselectAll([silent])

    Deselects all items in the selectmenu.

    Parameters
    • Name
      silent
      Type
      Boolean
      Description
      Pass in as true to prevent the change event from emitting. Default value is false.

  • instance.select(value[, silent])

    Selects item(s) in the selectmenu..

    Parameters
    • Name
      value
      Type
      String
      Description
      An option value or combination of option values joined with "|||".
    • Name
      silent
      Type
      Boolean
      Description
      Pass in as true to prevent the change event from emitting. Default value is false.

  • instance.disable()

    Disables the selectmenu UI if currently enabled.

    • No params required.

  • instance.enable()

    Enables the selectmenu UI if currently disabled.

    • No params required.

  • instance.update()

    Make changes to your native (root) select element, then call this method to apply changes to the selectmenu UI.

    Parameters
    • Name
      config
      Type
      Object
      Description
      Configuration object used to rewrite current properties..

Properties

  • instance.rootelement

    The wrapped select child node living in the provided root.

  • instance.element

    The raw select child node living in the provided root.

  • instance.version

    Selectmenu version

  • instance.multiple

    Boolean representing if the selectmenu is a multi-select or not.

  • instance.disabled

    Boolean representing if the selectmenu is currently disabled.

  • instance.enabled

    Boolean representing if the selectmenu is currently enabled.

  • instance.options

    The raw option elements.

  • instance.trigger

    TThe wrapped, rendered trigger root.

  • instance.input

    The wrapped, rendered triggering input element.

  • instance.list

    The wrapped, rendered UI list.

  • instance.items

    The wrapped, rendered UI list items.

  • instance.listOptions

    The wrapped, rendered UI list options (different than items, typically nested in an item).

  • instance.isHidden

    Boolean representing if the list is hidden or not.

  • instance.isOpen

    Boolean representing if the list is open (not hidden) or not.

  • instance.value

    Single [or array] of value(s) currently selected.