Jekyll One

Fulltext Search

MsDropdown is a lightweight jQuery plugin to enable the use of images or font icons for HTML select-based dropdown menus. The HTML standard does not support the use of images or icons in menus or dropdown lists. MsDropdown helps to make menu and dropdown entries more understandable and eye-catching. Additional menu icons can help clarify much of what is behind.

10-30 Minutes to read

The MsDropdown manual pages are based on MsDropdown version 4.0.3, a version modified and optimized for the J1 Template version 2026.1.1. The idea of providing this documentation is not to simply copy the original MsDropdown pages as duplicates. For better readability and usability, all pages are restructured and enhanced by code examples and improved description texts.

Getting started

A standard HTML dropdown is created with the <select> element. The HTML standard, however, does not allow images or icons inside the entries of a <select> list. This is where MsDropdown comes in: the module takes an existing <select> element and rebuilds it as a modern looking dropdown that can show images, icons and description texts for every entry.

The important part: the original <select> element is not removed from the page. It is only hidden and kept in sync with the new dropdown in the background. Whatever a visitor selects in the MsDropdown list is written back to the hidden <select> element. For that reason, MsDropdown works with normal HTML forms out of the box — a form still submits the value of the underlying <select> element, and the required attribute is fully supported as well.

How MsDropdown works

MsDropdown is implemented as a web component, a so-called customized built-in element that extends the native <select> element under the name ms-dropdown. As soon as a <select> element carries the attribute is="ms-dropdown", the browser upgrades the element automatically when the page is loaded — you do not need to write any JavaScript code for that.

<select name="example" is="ms-dropdown">
  <option value="one" data-image="/assets/image/icons/one.png">One</option>
  <option value="two" data-image="/assets/image/icons/two.png">Two</option>
</select>

All visual extras of an entry (image, icon, tooltip text, description) are configured by simple data-* attributes on the <option> elements. You can find all supported attributes in the section Attributes of this manual.

The Safari browser does not support customized built-in elements. The MsDropdown module detects Safari automatically and converts all <select> elements marked with is="ms-dropdown" by script instead. As a user of the module, you do not need to do anything — the markup is the same for all browsers.

How MsDropdown is used in J1 Template

Good news first: the MsDropdown module is fully integrated in the J1 Template. The JavaScript and all stylesheets are already part of the theme, so no installation is needed. The integration consists of the following building blocks:

The core module (msDropdown.js)

The MsDropdown library (version 4.0.3), modified and optimized for the J1 Template. The module is located in the theme folder ~/assets/theme/j1/modules/msDropdown/js/. It registers the web component ms-dropdown and provides the JavaScript API described in the section Programming Interface.

The core styles (msDropdown.css)

The stylesheet that gives the dropdown its look and feel. The J1 Template ships a theme-adapted version located at ~/assets/theme/j1/modules/msDropdown/css/themes/uno/msDropdown.css.

The flag icons (flags.css)

An optional stylesheet that provides small country flag icons as a single CSS sprite image. The flags are used via the attribute data-image-css="flag <country-code>", for example flag de for Germany. This is the easiest way to build country or language selection dropdowns without managing dozens of image files.

Activating a dropdown

There are two ways to turn a <select> element into a MsDropdown:

By markup (recommended)

Add the attribute is="ms-dropdown" to the <select> element. The dropdown is created automatically when the page is loaded. This is the way all examples of this manual use.

By JavaScript

Create the dropdown by script, for example if the <select> element is added to the page dynamically:

// using a CSS selector ..
MsDropdown.make('#my_select');
// .. or using a DOM element
new MsDropdown(document.getElementById('my_select'));

Both ways accept the same set of options. When creating by markup, the options are passed as data- attributes on the <select> element; when creating by JavaScript, the options are passed as a *settings object in camelCase notation. See the section Attributes for all available options and the section Examples for ready-to-use code.

Programming Interface

Once a <select> element has been converted, MsDropdown offers a complete JavaScript API (Application Programming Interface) to work with a dropdown by script. The API consists of properties to read and change the state of a dropdown (for example, the selected entry) and methods to control its behavior (for example, to open or close the options list, or to add and remove entries).

You do not need the API for everyday use — dropdowns configured by markup work without any scripting. The API becomes useful when a page should react to user input, for example, to load new content whenever the selection changes.

Properties

Properties describe the current state of a dropdown. Most properties can be both read (getter) and changed (setter): reading selectedIndex tells you which entry is currently selected, while assigning a new value to selectedIndex selects a different entry and updates the dropdown on the page. Some properties are marked readonly; they can be read but not changed. Where possible, the properties follow the standard properties of a native <select> element, so they will feel familiar if you have worked with HTML forms before.

Table 1. MsDropdown properties
Name Description

selectedIndex

This property is used to set and get the selected index.

let ddSelect = document.getElementById("tech").msDropdown;
ddSelect.selectedIndex = 3;
let index = ddSelect.selectedIndex;

options

This returns <option> (HTMLOptionsCollection) elements. You can set the length of option with this property too.

optionsUI (readonly)

This returns the list items (<li> elements) of the dropdown UI that represent the options.

length

To set and get the length of the options.

value

Returns the selected value

selectedText (readonly)

This returns the selected text of the dropdown.

disabled

To make dropdown enable or disabled. You won’t be able to interact with msDropdown when it is disabled.

form (readonly)

This returns the associated <form> else null.

multiple

This property is used to set or get the multiple. You may be able to select more than one item if multiple is true.

name

This returns the name of the <select>. I should mention here; msDropdown borrows the name from the original dropdown to work the "required" attribute.

required

A Boolean attribute indicating that an option with a non-empty string value must be selected. Here is a surprise; you can change the default message too. Just set the data-error-message="Your custom message here" in <select>.

size

If the size is greater than 1, It will be converted as a list. The size determines the number of rows to show.

selectedOptions (readonly)

It returns the selected <option>.

children (readonly)

It returns the list of options.

uiData (readonly)

It returns the selected data. You may find the following properties in this one object. isArray will be true if data,UI, index etc will be return as an array.

{data: {
        "image": "../dist/images/icons/icon_games.gif",
        "title": "",
        "description": "",
        "value": "games",
        "text": "Games",
        "className": "",
        "imageCss": "",
        "index": 2,
        "selected": true,
        "disabled": false,
        "internalStyle": ""
        },
        ui: <li>,
        index: 2,
        option: <options>,
        isArray:false
}

version (readonly)

This returns the current version of the msDropdown.

Access on properties

When a <select> element has been converted, the element gets a new property named msDropdown. This property holds the MsDropdown instance of that element, and all public properties and methods of the API are accessed through this instance. The example below reads the instance of a dropdown with the id tech:

let ddSelect = document.getElementById("tech").msDropdown;

With the instance at hand, all properties from the table above can be read and set. Try it out in the developer console of your browser:

// select the first entry
ddSelect.selectedIndex = 0;
// read the selected text
console.log(ddSelect.selectedText);

Methods

Methods are the actions a dropdown can perform. They are called as functions on the MsDropdown instance, for example ddSelect.open() to open the options list by script. The table below lists all public methods, together with their arguments and small code examples.

Table 2. Public methods
Name Description

setSettingAttribute

Set the settings attributes, and you have an option to remake the msDropdown by passing true in the last argument.

[source, js] ---- /** * * @param key * @param value * @param shouldRefresh */ setSettingAttribute(key, value, shouldRefresh); ----

Below are available keys and default values:

[source, js] ---- { byJson: { data: null, selectedIndex: 0, name: null, size: 0, multiple: false, width: 250 }, mainCss: 'ms-dd', rowHeight: null, visibleRows: null, showIcon: true, zIndex: 9999, event:'click', style: '', childWidth:null, childHeight:null, enableCheckbox:false, checkboxNameSuffix:'_mscheck', showPlusItemCounter:true, enableAutoFilter:true, showFilterAlways:false, showListCounter:false, imagePosition:'left', errorMessage:'Please select an item from this list', on: {create: null,open: null,close: null,add: null,remove: null, change: null,blur: null,click: null,dblclick: null,mousemove: null, mouseover: null,mouseout: null,focus: null,mousedown: null,mouseup: null} } ----

add

Add an item to select. You can pass second param as index; where you want to insert this item.

[source, js] ---- /** * Object can be pass as below * new Option("Label", "value") or * {text:"Label", value:"value"} * or Label as string * or full object ie {text:"", value:"", description:'', image:'', className:'' title:'', imageCss:''} * @param obj {option | object} * @param index {int} */ add(item, index);

ddSelect.add("HashtagCms"); ddSelect.add(new Option("HashtagCms", "https://www.hashtagcms.org")); ddSelect.add({text:"HashtagCms", value:"https://www.hashtagcms.org"}); ddSelect.add({text:"HashtagCms", value:"https://www.hashtagcms.org", description:"Laravel Open Source CMS"}); ----

remove

Remove an item from <select>. And it returns the removed item with uiData.

[source, js] ---- /** * @param index {int} * @return uiData */ remove(index) ----

next

Move to the next index/item

[source, js] ---- next() ----

previous

Move to the previous index/item

[source, js] ---- previous() ----

open

Open the dropdown

[source, js] ---- open() ----

close

Close the dropdown

[source, js] ---- close() ----

namedItem

Returns the <option> element that carries a given name attribute, for example <option name="cd"></option>. Pass withData=true to get the uiData object of that entry as well.

[source, js] ---- /** * @param name {string} * @param withData {boolean} */ namedItem(name, withData) ----

item

Return <option> element based on the index that you have passed in the argument. uiData will also be returned if you pass withData=true

[source, js] ---- /** * @param index {int} * @param withData {boolean} */ item(index, withData) ----

visible

Shows or hides the options list, or returns the current visibility status when called without an argument.

[source, js] ---- /** * @param isShow * @return {boolean} */ visible(isShow) ----

showRows | visibleRows

Calculate first item height and set child height.

[source, js] ---- /** * @param numberOfRows {int} */ showRows(numberOfRows) ----

on

Add an event on the dropdown. Below are possible event types you can pass in the argument:

create | open | close | add | remove | change | blur | click | dblclick | mousemove | mouseover | mouseout | focus | mousedown | mouseup

[source, js] ---- /** * @param type {string} * @param fn {function} */ on(type, fn) ----

.Example [source, js] ---- ddSelect.on("change", function() { console.log(ddSelect.uiData) }); ----

off

Remove event listener.

[source, js] ---- /** * @param type {string} * @param fn {function} */ off(type, fn); ----

updateUiAndValue

Re-synchronizes the dropdown UI and its value with the underlying <select> element, in case the UI was not updated automatically.

[source, js] ---- updateUiAndValue() ----

refresh

Destroys and re-creates the dropdown UI from the current state of the underlying <select> element. Useful after many changes at once.

[source, js] ---- refresh() ----

destroy

Remove msDropdown and returns back to the original dropdown.

[source, js] ---- destroy() ----

Attributes

A MsDropdown is configured completely by attributes in the HTML markup — no JavaScript is needed. Three groups of attributes are available: the standard attributes of the <select> element, the data attributes on the <select> element that control the look and behavior of the dropdown, and the additional data attributes on the <option> elements that add images, icons and description texts to the single entries.

Besides the standard attributes and properties like selectedIndex, options, name, size or multiple, MsDropdown reads the following attributes of the <select> element, too:

Table 3. MsDropdown Attributes
Name Description

autofocus

As the name suggests, this attribute lets you choose that a form control should have autofocus when the page is loaded. Only one element can have autofocus.

disabled

If this property is enabled, you won’t be able to interact with the element.

form

Returns the <form> element the <select> is associated with, or null if there is none. This is a readonly property.

name

Returns the name of the <select> element. MsDropdown borrows the name from the original element, so the required validation of forms keeps working.

required

A Boolean attribute indicating that an option with a non-empty string value must be selected. Here is a surprise; you can change the default message too. Just set the data-error-message="Your custom message here" in <select>.

Data attributes

The look and behavior of a dropdown is controlled by data- attributes set on the <select> element itself. All of them are *optional — if an attribute is missing, its default value is used. The attributes are live: if one of them is changed by script at runtime, the settings are updated and the dropdown is refreshed automatically.

When a dropdown is created by JavaScript instead of markup, the same options are passed as keys of the settings object. The key name is the attribute name without the data- prefix, written in camelCase notation: the attribute data-child-width="300" becomes the settings key childWidth: '300'.

Table 4. MsDropdown data attributes
Name Default Description

data-main-css

ms-dd

The base CSS class used for all elements of the dropdown UI. Change this attribute only if you provide a complete custom stylesheet.

data-show-icon

true

Show (true) or hide (false) the images and icons of the entries.

data-event

click

The mouse event that opens the options list. Possible values are click and mouseover.

data-child-width

null

A fixed width for the options list (in pixels), for example data-child-width="300". If not set, the list is as wide as the dropdown itself.

data-child-height

null

A fixed height for the options list (in pixels), for example data-child-height="315". If the entries need more space, the list becomes scrollable.

data-visible-rows

null

The number of entries (rows) shown in the options list before the list becomes scrollable. An alternative to data-child-height that does not require pixel values.

data-enable-checkbox

false

Show a checkbox in front of every entry (true). Checkboxes require a <select> element with the multiple attribute; if multiple is missing, it is turned on automatically.

data-checkbox-name-suffix

_mscheck

The suffix added to the field name of the generated checkboxes when data-enable-checkbox is enabled.

data-enable-auto-filter

true

Show a filter (search) box at the top of the options list (true). The list is filtered while the user types.

data-show-filter-always

false

Keep the filter box visible at all times (true) instead of showing it only while the options list is open.

data-show-plus-item-counter

true

For multiple selections: show the first selected entry followed by a counter like +2 for the additional selected entries (true).

data-show-list-counter

false

Show the total number of entries as a counter in the dropdown header (true).

data-image-position

left

The position of the images and icons within an entry. Possible values are left and right.

data-error-message

Please select an item from this list

The validation message shown when a <select> element carries the required attribute and the form is submitted without a selection.

Additional attributes

The single entries of a dropdown are configured on the <option> elements. Besides the standard value, text, selected, disabled, class, and style properties, MsDropdown reads the following (additional) data attributes on every <option> element, too:

Table 5. MsDropdown additional attributes
Name Description

data-image

This attribute is used to display an image in an item. The value is the path (URL) of the image file, for example data-image="/assets/image/icons/mail.png".

data-title

If you need to display any text on hover of an item. The text is shown as a small tooltip while the mouse pointer rests on the entry.

data-description

To display a description along with the text in the next line. The description is shown in a smaller, muted font below the entry text.

data-image-css

You may use this if you want to display an image using CSS. The value is a list of CSS class names instead of an image file. The J1 Template ships the stylesheet flags.css for this purpose: the classes flag <country-code> display small country flags from a single CSS sprite image, for example data-image-css="flag de" for Germany.

Examples

The following examples show the most common ways to use MsDropdown, from a simple image dropdown to option groups, checkbox lists, country flags via CSS, and dropdowns created from JSON data. All examples are ready to use: copy the markup into a page, adjust the image paths and option values, and the dropdown is created automatically when the page is loaded.

Simple dropdown

There are two ways to apply MsDropdown on a <select> element:

  1. You can add the is="ms-dropdown" attribute to the <select> element, like in the example below. The dropdown is then created automatically when the page is loaded.

<select class="tech" name="tech" is="ms-dropdown">
  <option value="" selected>Please select one</option>
  <option data-image="./dist/images/icons/icon_email.gif" value="email">Email</option>
  <option data-image="./dist/images/icons/icon_faq.gif" value="faq">FAQ</option>
  <option data-image="./dist/images/icons/icon_games.gif" value="games">Games</option>
  <option data-image="./dist/images/icons/icon_music.gif" value="music">Music</option>
  <option data-image="./dist/images/icons/icon_phone.gif" value="phone">Phone</option>
  <option data-image="./dist/images/icons/icon_sales.gif" value="graph">Graph</option>
  <option data-image="./dist/images/icons/icon_secure.gif" value="secured">Secured</option>
  <option data-image="./dist/images/icons/icon_video.gif" value="video">Video</option>
  <option data-image="./dist/images/icons/icon_cd.gif" name="cd" value="cd">CD</option>
</select>

  1. You can create the dropdown by JavaScript. This is only needed for <select> elements without the is="ms-dropdown" attribute, for example elements that are added to the page dynamically.

In case you want to convert later by script, you can use the below code. You may use a CSS selector too.

MsDropdown.make('#select_element');
//or
new MsDropdown('.select_elements');

Dropdown with description

Did you notice? There is an extra attribute data-description in <option>.

<select id="payments" name="payments" is="ms-dropdown" data-enable-auto-filter="false" required>
  <option value="" data-description="Choose your payment gateway">Payment Gateway</option>
  <option value="amex" data-image="./dist/images/icons/Amex-56.jpg" data-description="My life. My card...">Amex</option>
  <option value="Discover" data-image="./dist/images/icons/Discover-56.jpg" data-description="It pays to Discover...">Discover</option>
  <option value="Mastercard" data-image="./dist/images/icons/Mastercard-56.jpg" data-title="For everything else..." data-description="For everything else...">Mastercard</option>
  <option value="cash" data-image="./dist/images/icons/Cash-56.jpg" data-description="Pay at your doorstep...">Cash on delivery</option>
  <option value="Visa" data-image="./dist/images/icons/Visa-56.jpg" data-description="All you need...">Visa</option>
  <option value="Paypal" data-image="./dist/images/icons/Paypal-56.jpg" data-description="Pay and get paid...">Paypal</option>
</select>

Dropdown with checkboxes

With the attribute data-enable-checkbox="true", every entry gets a checkbox and more than one entry can be selected at a time.

<select name="tech_with_checkbox" is="ms-dropdown" data-enable-checkbox="true">
  <option data-image="./dist/images/icons/icon_email.gif"  value="email">Email</option>
  <option data-image="./dist/images/icons/icon_faq.gif"  value="faq">FAQ</option>
  <option data-image="./dist/images/icons/icon_games.gif"  selected value="games">Games</option>
  <option data-image="./dist/images/icons/icon_music.gif" value="music">Music</option>
  <option data-image="./dist/images/icons/icon_phone.gif" value="phone">Phone</option>
  <option data-image="./dist/images/icons/icon_sales.gif"  value="graph">Graph</option>
  <option data-image="./dist/images/icons/icon_secure.gif" value="secured">Secured</option>
  <option data-image="./dist/images/icons/icon_video.gif" value="video">Video</option>
  <option data-image="./dist/images/icons/icon_cd.gif" name="cd" value="cd">CD</option>
</select>

Option groups

<select is="ms-dropdown" name="car_group">
  <optgroup label="Mercedes Benz">
    <option>Mercedes-Benz GLA</option>
    <option>Mercedes-Benz S-Class</option>
    <option>Mercedes-Benz E-Class</option>
    <option>Mercedes-Benz GLS</option>
  </optgroup>
  <optgroup label="Jaguar">
    <option>Jaguar F-TYPE</option>
    <option selected>Jaguar XE</option>
    <option>Jaguar F-Pace</option>
    <option>Jaguar I-Pace</option>
    <option>Jaguar XF</option>
  </optgroup>
</select>

Dropdown with CSS images

<select name="countries" id="countries" is="ms-dropdown" data-child-height="315">
  <option value='ad' data-image-css="flag ad" data-title="Andorra">Andorra</option>
  <option value='ae' data-image-css="flag ae" data-title="United Arab Emirates">United Arab Emirates</option>
  <option value='af' data-image-css="flag af" data-title="Afghanistan">Afghanistan</option>
  ...
  <option value='zr' data-image-css="flag zr" data-title="Zaire (former)">Zaire (former)</option>
  <option value='zw' data-image-css="flag zw" data-title="Zimbabwe">Zimbabwe</option>
</select>

Dropdown as a list

If the size attribute is greater than 1, the dropdown is rendered as an open list that shows the given number of rows. Together with the multiple attribute, visitors can select several entries at once.

<select name="gameList[]" is="ms-dropdown" multiple size="5">
  <option value="" selected>Please select one</option>
  <option data-image="./dist/images/icons/icon_email.gif"  value="email">Email</option>
  <option data-image="./dist/images/icons/icon_faq.gif"  value="faq">FAQ</option>
  <option data-image="./dist/images/icons/icon_games.gif"  value="games">Games</option>
  <option data-image="./dist/images/icons/icon_music.gif" value="music">Music</option>
  <option data-image="./dist/images/icons/icon_phone.gif" value="phone">Phone</option>
  <option data-image="./dist/images/icons/icon_sales.gif"  value="graph">Graph</option>
  <option data-image="./dist/images/icons/icon_secure.gif" value="secured">Secured</option>
  <option data-image="./dist/images/icons/icon_video.gif" value="video">Video</option>
  <option data-image="./dist/images/icons/icon_cd.gif" name="cd" value="cd">CD</option>
</select>

Create Dropdown from JSON object

[
  {description:'Choose your payment gateway', value:'', text:'Payment Gateway'},
  {image:'/assets/mywork/web-components/image-dropdown/images/icons/Amex-56.jpg', description:'My life. My card...', value:'amex', text:'Amex'},
  {image:'/assets/mywork/web-components/image-dropdown/images/icons/Discover-56.jpg', description:'It pays to Discover...', value:'Discover', text:'Discover'},
  {image:'/assets/mywork/web-components/image-dropdown/images/icons/Mastercard-56.jpg', title:'For everything else...', description:'For everything else...', value:'Mastercard', text:'Mastercard'},
  {image:'/assets/mywork/web-components/image-dropdown/images/icons/Cash-56.jpg', description:'Sorry not available...', value:'cash', text:'Cash on delivery', disabled:true},
  {image:'/assets/mywork/web-components/image-dropdown/images/icons/Visa-56.jpg', description:'All you need...', value:'Visa', text:'Visa'},
  {image:'/assets/mywork/web-components/image-dropdown/images/icons/Paypal-56.jpg', description:'Pay and get paid...', value:'Paypal', text:'Paypal'}
];

Below method is being called on "Click here to convert by above json" button.

<script>
  function makeDd() {
    'use strict';
    // get the data from above json string
    let json = new Function(`return ${document.getElementById('json_data').innerHTML}`)();
    // clean the holder
    document.getElementById("json_dropdown").innerHTML = "";
    // convert to msDropdown
    MsDropdown.make("#json_dropdown", {
        byJson: {
            data: json, selectedIndex: 0, name: "json_dropdown",
            size: 0, multiple: false, width: 450
        },
        enableAutoFilter:false
    });
  }
</script>

What are the settings params

If you are creating with the help of JavaScript you might need this. So, how do you create it? Syntax is below

//Style 1
MsDropdown.make("element", {...settings});
//Style 2
new MsDropdown(document.getElementById("element_id"), {...settings});

And what are the settings params you can pass to the msDropdown? It is similar to the data-attributes, those I’ve mentioned above in this document. Only difference is that you passed as a camelCase key without the "data-". For example if you want to set child width, you passed in attribute as data-child-width="300px" whereas you need to pass in settings as childWidth:'300px'

So, here is an example what you can pass in settings.

MsDropdown.make("element", {
  byJson: {
      data: null, selectedIndex: 0, name: null,
      size: 0, multiple: false, width: 250
      },
  mainCss: 'ms-dd',
  rowHeight: null,
  visibleRows: null,
  showIcon: true,
  zIndex: 9999,
  event:'click',
  style: '',
  childWidth:null,
  childHeight:null,
  enableCheckbox:false,
  checkboxNameSuffix:'_mscheck',
  showPlusItemCounter:true,
  enableAutoFilter:true,
  showFilterAlways:false,
  showListCounter:false,
  imagePosition:'left',
  errorMessage:'Please select an item from this list',
  on: { create: null,open: null,close: null,add: null,remove: null,
        change: null,blur: null,click: null,dblclick: null,mousemove: null,
        mouseover: null,mouseout: null,focus: null,mousedown: null,
        mouseup: null
      }
});