Jekyll One

QuickSearch

This page is under construction. An updated version will be available soon.

MsDropdown is a lightweight jQuery library to enable the use of images (or icons) for HTML <select> based dropdown menus. The HTML standard does not support the use of images or icons in menu/dropdown lists. MsDropdown helps to make menu entries better understandable, and eye-minded. Additional menu icons can support understanding what is behind a lot.

MsDropdown API

Enim dolores incidunt harum aut rerum temporibus reprehenderit similique qui eveniet accusantium atque ipsam. Officia sit perspiciatis ea aliquam vel nulla est. Dolores consectetur vel optio reprehenderit. Fugit repellat consequatur placeat nihil ipsam voluptas. Aut veniam ad non.

Attributes

Besides selectedIndex, options, name, size, multiple, etc attributes/properties, msDropdown reads below attributes too.

Table 1. 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

It returns the name of the <form> element to associate the <select> with. This is readonly property.

name

It returns the name of the <select> element.

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

Similique sint eaque ut. Quas ut ut et facilis quisquam perferendis. Hic repudiandae nisi nam eos itaque quas reprehenderit et ducimus quia repellendus non debitis omnis. Nam quia eveniet atque sapiente iusto ducimus provident voluptatem qui quae repellat et. Ut illum quae ipsum consequatur eligendi eos dolor reiciendis accusamus.

Table 2. MsDropdown Data attributes
Name Description

data-main-css

This is the main CSS class. Default value is ms-dd

data-show-icon

If you are in need to hide the icon on the header. The default value is: true

data-event

To interact msDropdown with an event. The default value is: click

data-child-width

Sometimes you need a list of children bigger than the dropdown. This can help. The default value is: null or whatever is defined in the CSS.

data-child-height

By default, it shows all the options listed in the dropdown. If you need to show some rows you can use this attribute. The default value is: null

data-enable-checkbox

If you enable this; multiple will automatically set to true. It shows a checkbox with each list item. The default value is: false

data-checkbox-name-suffix

If the checkbox is enabled; there is an extra field will be posted with the form. Say <select> name is "tech" and checkbox is enabled, tech_mscheck[] will be posted as an array. The default value is: {select_name}_mscheck

data-enable-auto-filter

It lets you search by typing any key when msDropdown is open. Just like auto-suggest. The default value is: true

data-visible-rows

If you set this attribute, it calculates the max height of the items and sets the child height based on the number provided in value. You can also achieve this by using the data-child-height property, only that set in pixels. The default value is: null

data-show-plus-item-counter

If multiple is true and you select more than one item; it shows a text +N. N denotes numbers here. The default value is: true

data-error-message

If required is enabled in <select> it shows a required message. Guess what? You can change that by setting this attribute. The default value is: Please select an item from this list

Besides value, text, selected, disabled, class, and style properties MsDropdown reads the below (additional) attributes too.

Table 3. MsDropdown additional attributes
Name Description

data-image

This attribute is used to display an image in an item.

data-title

If you need to display any text on hover of an item.

data-description

To display a description along with the text in the next line.

data-image-css

You may use this if you want to display an image using CSS.

Setter and Getter properties

Explicabo nesciunt voluptate illum quia rerum facilis rem eligendi modi iste vero. Ipsum ipsum quia laborum eum voluptate eos voluptatibus est officia. Cum excepturi ullam quam ipsum est at dicta consectetur quo velit qui est provident. Fuga qui rerum ut culpa veritatis perferendis laudantium. Dolorem nesciunt vero error maxime rerum deserunt.

Table 4. 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.

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

Here is an example. The below dropdown id is "tech". Each element has a new property called "msDropdown" once it’s converted to msDropdown/image dropdown. You can access all the public properties and methods from that one.

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

Select a property:

Reminder: I’ve made ddSelect as a global variable on this page. You can play with that in console.

selectedIndex options length selectedText disabled form multiple name required size selectedOptions children uiData

Try to copy-paste the below code in the console. You can set and get all the properties.

ddSelect.selectedIndex = 0;

Public methods

Table 5. 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.

/**
*
* @param key
* @param value
* @param shouldRefresh
*/
setSettingAttribute(key, value, shouldRefresh);

Below are available keys and default values:

{
  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,
  showListCounter:false,
  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.

/**
* 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.

/**
* @param index {int}
* @return uiData
*/
remove(index)

next

Move to the next index/item

next()

previous

Move to the previous index/item

previous()

open

Open the dropdown

open()

close

Close the dropdown

close()

namedItem

If you have given any name of an option, will be returned. say, <option name="cd"></option>

/**
* @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

/**
* @param index {int}
* @param withData {boolean}
*/
item(index, withData)

visible

Show hide or get status of visibility.

/**
* @param isShow
* @return {boolean}
*/
visible

showRows | visibleRows

Calculate first item height and set child height.

/**
* @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

/**
* @param type {string}
* @param fn {function}
*/
on(type, fn)
Example
ddSelect.on("change", function() {console.log(ddSelect.uiData});

off

Remove event listener.

/**
* @param type {string}
* @param fn {function}
*/
off(type, fn);

updateUiAndValue

In case there UI is not updated. You can call this method.

updateUiAndValue()

refresh

Recreatea a msDropdown.

refresh()

destroy

Remove msDropdown and returns back to the original dropdown.

destroy()

Examples

At voluptatem libero aut nemo dignissimos quia dignissimos eum eos quia aut. Harum mollitia et amet ipsam ipsa. Non eos earum repudiandae ex voluptatem blanditiis est cupiditate ducimus molestias molestias. Non reprehenderit vel sed illum error voluptas rerum recusandae vitae magni saepe quia beatae. Tempore est corporis consequatur placeat.

Simple dropdown

Email FAQ Games Music Phone Graph Secured Video CD

There are two ways that you can apply msDropdown on <select> element

  1. You can add `is="ms-dropdown"`attributes. Like we have in the below example.

<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 don’t need the below code if you have already included dd.min.js in the bottom of the page. Like I’ve mentioned in the installation section.

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

Email FAQ Games Music Phone Graph Secured Video CD

<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

Please select one Email FAQ Games Music Phone Graph Secured Video CD

<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
    });
    //or we can use like this too.
    /*new MsDropdown(document.getElementById("json_dropdown"), {
        byJson: {
            data: json, name: "json_dropdown"
        }
    });*/
  }
</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,
  showListCounter:false,
  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
      }
});