docs

Multiple Select

Multiple select is a jQuery plugin to select multiple elements with checkboxes :).

Multiple Selected is licensed under the The MIT License. Completely free, you can arbitrarily use and modify this plugin. If this plugin is useful to you, you can give me a star, and I will do better, thanks.

Current version: 1.2.1

Requirements

jQuery >= 1.7.0

Features

Default option allows to show checkbox.
Ability to grouping elements.
Supports to show multiple items in single row.
Select all options.
Feature to show placeholder.

Browser Compatibility

IE 7+
Chrome 8+
Firefox 10+
Safari 3+
Opera 10.6+

Examples

The Basics1

Multiple Select can take a regular select box like this:

January February March April May June July August September October November December

and turns it into:

<head>
	<link href="multiple-select.css" rel="stylesheet"/>
</head>
<body>
	<select multiple="multiple">
	    <option value="1">January</option>
	    ...
	    <option value="12">December</option>
	</select>
	<script src="multiple-select.js"></script>
	<script>
		$('select').multipleSelect();
	</script>
</body>

The Basics2

Multiple Select can take a regular select box like this:

January February March April May June July August September October November December

and turns it into:

<head>
	<link href="multiple-select.css" rel="stylesheet"/>
</head>
<body>
	<select multiple="multiple" disabled="disabled">
	    <option value="1">January</option>
	    ...
	    <option value="12">December</option>
	</select>
	<script src="multiple-select.js"></script>
	<script>
		$('select').multipleSelect();
	</script>
</body>

The Basics3

Multiple Select can take a regular select box like this:

January February March April May June July August September October November December

and turns it into:

<head>
	<link href="multiple-select.css" rel="stylesheet"/>
</head>
<body>
	<select multiple="multiple">
	    <option value="1" selected="selected">January</option>
		<option value="2" disabled="disabled">February</option>
	    <option value="3" selected="selected" disabled="disabled">March</option>
	    ...
	</select>
	<script src="multiple-select.js"></script>
	<script>
		$('select').multipleSelect();
	</script>
</body>

With Optgroups1

Multiple Select can take a regular select box like this:

Option 1 Option 2 Option 3 Option 4 Option 5 Option 6 Option 7 Option 8 Option 9

and turns it into:

<head>
	<link href="multiple-select.css" rel="stylesheet"/>
</head>
<body>
	<select multiple="multiple">
	    <optgroup label="Group 1">
			<option value="1">Option 1</option>
			...
		</optgroup>
		...
		<optgroup label="Group 3">
			...
			<option value="9">Option 9</option>
		</optgroup>
	</select>
	<script src="multiple-select.js"></script>
	<script>
		$('select').multipleSelect();
	</script>
</body>

With Optgroups2

Multiple Select can take a regular select box like this:

Option 1 Option 2 Option 3 Option 4 Option 5 Option 6 Option 7 Option 8 Option 9

and turns it into:

<head>
	<link href="multiple-select.css" rel="stylesheet"/>
</head>
<body>
	<select multiple="multiple">
	    <optgroup label="Group 1" disabled="disabled">
			<option value="1">Option 1</option>
			...
		</optgroup>
		...
		<optgroup label="Group 3">
			...
			<option value="9">Option 9</option>
		</optgroup>
	</select>
	<script src="multiple-select.js"></script>
	<script>
		$('select').multipleSelect();
	</script>
</body>

The Placeholder

January February March April May June July August September October November December

<head>
	<link href="multiple-select.css" rel="stylesheet"/>
</head>
<body>
    <select multiple="multiple">
        <option value="1">January</option>
        ...
        <option value="12">December</option>
    </select>
    <script src="multiple-select.js"></script>
    <script>
        $("select").multipleSelect({
        	placeholder: "Here is the placeholder"
        });
    </script>
</body>

The Multiple Items

Multiple Select supports to show multiple items in single row.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30

<head>
	<link href="multiple-select.css" rel="stylesheet"/>
</head>
<body>
    <select multiple="multiple">
        <option value="1">1</option>
        ...
        <option value="30">30</option>
    </select>
    <script src="multiple-select.js"></script>
    <script>
        $("select").multipleSelect({
        	width: 460,
        	multiple: true,
            multipleWidth: 55
        });
    </script>
</body>

With Optgroups

Multiple Select supports to show multiple items in single row with optgroups.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

<head>
	<link href="multiple-select.css" rel="stylesheet"/>
</head>
<body>
    <select multiple="multiple">
        <optgroup label="Group 1">
			<option value="1">1</option>
			...
		</optgroup>
        ...
        <optgroup label="Group 3">
			<option value="15">15</option>
		</optgroup>
    </select>
    <script src="multiple-select.js"></script>
    <script>
        $("select").multipleSelect({
        	multiple: true,
            multipleWidth: 55,
            width: '100%'
        });
    </script>
</body>

The Hide Select All

First Second Third Fourth

<head>
	<link href="multiple-select.css" rel="stylesheet"/>
</head>
<body>
    <select multiple="multiple">
        <option value="1">First</option>
        ...
        <option value="4">Fourth</option>
    </select>
    <script src="multiple-select.js"></script>
    <script>
        $("select").multipleSelect({
        	selectAll: false
        });
    </script>
</body>

The Single Row

First Second Third Fourth

<head>
	<link href="multiple-select.css" rel="stylesheet"/>
</head>
<body>
    <select multiple="multiple">
        <option value="1">First</option>
        ...
        <option value="4" selected="selected">Fourth</option>
    </select>
    <script src="multiple-select.js"></script>
    <script>
        $("select").multipleSelect({
        	single: true
        });
    </script>
</body>

The Position

Set the select dropdown in top position.

January February March April May June July August September October November December

<head>
	<link href="multiple-select.css" rel="stylesheet"/>
</head>
<body>
	<select multiple="multiple">
	    <option value="1">January</option>
	    ...
	    <option value="12">December</option>
	</select>
	<script src="multiple-select.js"></script>
	<script>
		$('select').multipleSelect({
		    position: 'top'
		});
	</script>
</body>

The Filter1

abc bcd cde def efg fgh ghi hij ijk jkl klm lmn mno nop opq pqr qrs rst stu tuv uvw vwx wxy xyz 123 234 345 456 567 678 789

<head>
	<link href="multiple-select.css" rel="stylesheet"/>
</head>
<body>
    <select multiple="multiple">
        <option value="1">abc</option>
        ...
        <option value="31">789</option>
    </select>
    <script src="multiple-select.js"></script>
    <script>
        $("select").multipleSelect({
        	filter: true
        });
    </script>
</body>

The Filter2

000 111 222 333 444 555 666 777 888 999 210 321 432 543 654 765 876 987 098 012 123 234 345 456 567 678 789 890

<head>
	<link href="multiple-select.css" rel="stylesheet"/>
</head>
<body>
    <select multiple="multiple">
		<optgroup label="Group 1">
			<option value="1">000</option>
			...
		...
    </select>
    <script src="multiple-select.js"></script>
    <script>
        $("select").multipleSelect({
        	filter: true,
        	multiple: true
        });
    </script>
</body>

The Keep Open

January February March April May June July August September October November December

<head>
	<link href="multiple-select.css" rel="stylesheet"/>
</head>
<body>
	<select multiple="multiple">
	    <option value="1">January</option>
	    ...
	    <option value="12">December</option>
	</select>
	<script src="multiple-select.js"></script>
	<script>
		$('select').multipleSelect({
		    isOpen: true,
		    keepOpen: true
		});
	</script>
</body>

The Styler

Custom the item style.

January February March April May June July August September October November December

<head>
	<link href="multiple-select.css" rel="stylesheet"/>
</head>
<body>
	<select multiple="multiple">
	    <option value="1">January</option>
	    ...
	    <option value="12">December</option>
	</select>
	<script src="multiple-select.js"></script>
	<script>
		$('select').multipleSelect({
		    styler: function(value) {
		        if (value == '1') {
                    return 'background-color: #ffee00; color: #ff0000;';
                }
                if (value == '6') {
                    return 'background-color: #000; color: #fff;';
                }
		    }
		});
	</script>
</body>

SetSelects/GetSelects

SetSelects GetSelects

Monday Tuesday Wednesday Thursday Friday Saturday Sunday

<head>
	<link href="multiple-select.css" rel="stylesheet"/>
</head>
<body>
	<button id="setSelectsBtn">SetSelects</button>
	<button id="getSelectsBtn">GetSelects</button>
    <select multiple="multiple">
        <option value="1">Monday</option>
        ...
        <option value="7">Sunday</option>
    </select>
    <script src="multiple-select.js"></script>
    <script>
        $("select").multipleSelect();
        $("#setSelectsBtn").click(function() {
        	$("select").multipleSelect("setSelects", [1, 3]);
        });
        $("#getSelectsBtn").click(function() {
        	alert("Selected values: " + $("select").multipleSelect("getSelects"));
            alert("Selected texts: " + $("select").multipleSelect("getSelects", "text"));
        });
    </script>
</body>

Enable/Disable

Enable Disable

Monday Tuesday Wednesday Thursday Friday Saturday Sunday

<head>
	<link href="multiple-select.css" rel="stylesheet"/>
</head>
<body>
	<button id="enableBtn">Enable</button>
	<button id="disableBtn">Disabled</button>
    <select multiple="multiple">
        <option value="1">Monday</option>
        ...
        <option value="7">Sunday</option>
    </select>
    <script src="multiple-select.js"></script>
    <script>
        $("select").multipleSelect();
        $("#setSelectsBtn").click(function() {
        	$("select").multipleSelect("enable");
        });
        $("#getSelectsBtn").click(function() {
        	$("select").multipleSelect("disable");
        });
    </script>
</body>

CheckAll/UncheckAll

CheckAll UncheckAll

Monday Tuesday Wednesday Thursday Friday Saturday Sunday

<head>
	<link href="multiple-select.css" rel="stylesheet"/>
</head>
<body>
	<button id="checkAllBtn" class="button">CheckAll</button>
    <button id="uncheckAllBtn" class="button">UncheckAll</button>
    <select multiple="multiple">
        <option value="1">Monday</option>
        ...
        <option value="7">Sunday</option>
    </select>
    <script src="multiple-select.js"></script>
    <script>
        $("select").multipleSelect();
        $("#checkAllBtn").click(function() {
        	$("select").multipleSelect("checkAll");
        });
        $("#uncheckAllBtn").click(function() {
        	$("select").multipleSelect("uncheckAll");
        });
    </script>
</body>

Focus/Blur

Focus Blur

Monday Tuesday Wednesday Thursday Friday Saturday Sunday

<head>
	<link href="multiple-select.css" rel="stylesheet"/>
</head>
<body>
	<button id="focusBtn" class="button">Focus</button>
	<button id="blurBtn" class="button">Blur</button>
    <select multiple="multiple">
        <option value="1">Monday</option>
        ...
        <option value="7">Sunday</option>
    </select>
    <script src="multiple-select.js"></script>
    <script>
        $("select").multipleSelect();
        $("#focusBtn").click(function() {
        	$("select").multipleSelect("focus");
        });
        $("#blurBtn").click(function() {
        	$("select").multipleSelect("blur");
        });
    </script>
</body>

The Refresh

Reloads the Multiple Select. If you're dynamically adding/removing option tags on the original select via AJAX or DOM manipulation methods, call refresh to reflect the changes.

Add + Refresh
Selected? Disabled?

1 2 3

<head>
	<link href="multiple-select.css" rel="stylesheet"/>
</head>
<body>
	<input id="refreshInput" type="text" required="required" />
	<button id="refreshAdd">Add + Refresh</button>
	<br />
	<label><input id="refreshSelected" type="checkbox" />Selected?</label>
	<label><input id="refreshDisabled" type="checkbox" />Disabled?</label>
    <select multiple="multiple">
        <option value="1">1</option>
        ...
        <option value="3">3</option>
    </select>
    <script src="multiple-select.js"></script>
    <script>
        $("select").multipleSelect();
        $("#refreshAdd").click(function() {
        	var $select = $("select"),
        		$input = $("#refreshInput"),
        		$selected = $("#refreshSelected"),
        		$disabled = $("#refreshDisabled"),
        		value = $.trim($input.val()),
        		$opt = $("<option />", {
					value: value,
					text: value
				});
        	if (!value) {
        		$input.focus();
        		return;
        	}
			if ($selected.is(":checked")){
				$opt.prop("selected", true);
			}
			if($disabled.is(":checked")){
				$opt.attr("disabled", true);
			}
			$input.val("");
			$select.append($opt).multipleSelect("refresh");
        });
    </script>
</body>

The Callbacks/Events

Here is the result of event.

000 111 222 333 444 555 666 777 888 999 210 321 432 543 654 765 876 987 098 012 123 234 345 456 567 678 789 890

<head>
	<link href="multiple-select.css" rel="stylesheet"/>
</head>
<body>
	<p id="eventResult">Here is the result of event.</p>
    <select multiple="multiple">
        <optgroup label="Group 1">
			<option value="1">000</option>
			...
		...
    </select>
    <script src="multiple-select.js"></script>
    <script>
        $("select").multipleSelect({
        	onOpen: function() {
        		$eventResult.text('Select opened!');
        	},
        	onClose: function() {
        		$eventResult.text('Select closed!');
        	},
        	onCheckAll: function() {
        		$eventResult.text('Check all clicked!');
        	},
        	onUncheckAll: function() {
        		$eventResult.text('Uncheck all clicked!');
        	},
        	onFocus: function() {
        		$eventResult.text('focus!');
        	},
        	onBlur: function() {
        		$eventResult.text('blur!');
        	},
        	onOptgroupClick: function(view) {
				var values = $.map(view.children, function(child){
					return child.value;
				}).join(', ');
				$eventResult.text('Optgroup ' + view.label + ' ' + 
					(view.checked ? 'checked' : 'unchecked') + ': ' + values);
			},
			onClick: function(view) {
				$eventResult.text(view.label + '(' + view.value + ') ' + 
					(view.checked ? 'checked' : 'unchecked'));
			}
        });
    </script>
</body>

Documentation

Constructor

isOpen

Type: boolean

Whether or not Multiple Select open the select dropdown.

By default this option is set to false.

placeholder

Type: string

A placeholder value can be defined and will be displayed until you select a item.

By default this option is set to ''.

selectAll

Type: boolean

Whether or not Multiple Select show select all checkbox.

By default this option is set to true.

selectAllText

Type: string

Multiple Select select all checkbox text.

By default this option is set to Select all.

selectAllDelimiter

Type: Array

Multiple Select select all checkbox delimiter.

By default this option is set to ['[',']'].

allSelected

Type: false or string

The text displays when the select all selected.

By default this option is set to All selected.

minimumCountSelected

Type: int

countSelected will be shown only if more than X items where selected.

By default this option is set to 3.

countSelected

Type: false or string

'#' is replaced with the count of selected items, '%' is replaces with total items.

By default this option is set to # of % selected.

ellipsis

Type: boolean

Add "..." after selected options if minimumCountSelected is set. Overrides countSelected option.

By default this option is set to false.

multiple

Type: boolean

Whether or not Multiple Select show multiple items in a row.

By default this option is set to false.

multipleWidth

Type: integer

Multiple Select show multiple items width.

By default this option is set to 80.

single

Type: boolean

Whether or not Multiple Select allows you to select only one option.

By default this option is set to false.

position

Type: string

Defines the position of select dropdown, can only be bottom or top.

By default this option is set to bottom.

filter

Type: boolean

Whether or not Multiple Select show a search field to search through checkbox items.

By default this option is set to false.

width

Type: integer/string

Define the width property of the dropdown list, support a percentage setting.

By default this option is set to undefined. Which is the same as the select input field.

maxHeight

Type: integer

Define the maximum height property of the dropdown list.

By default this option is set to 250.

keepOpen

Type: boolean

Keep the select dropdown always open.

By default this option is set to false.

styler

Type: function

The item styler function, return style string to custom the item style such as background: red. The function take one parameter: value.

styler: function(value) {
    if (value == '1') {
        return 'background-color: #ffee00; color: red;';
    }
}

Events

onOpen

Fires when the dropdown list is open.

onClose

Fires when the dropdown list is close.

onCheckAll

Fires when all the options are checked by either clicking the "Select all" checkbox, or when the "checkall" method is programatically called.

onUncheckAll

onFocus

Bind an event handler to the "focus".

onBlur

Bind an event handler to the "blur"

onOptgroupClick

Fires when a an optgroup label is clicked on.

onOptgroupClick: function(view) {
	/*
	view.label: the text of the optgroup
	view.checked: the checked of the optgroup
	view.children: an array of the checkboxes (DOM elements) inside the optgroup
	*/
}

onClick

Fires when a checkbox is checked or unchecked.

onClick: function(view) {
	/*
	view.label: the text of the checkbox item
	view.checked: the checked of the checkbox item
	*/
}

Methods

getSelects

Gets the selected values.

Parameter: type

Type: string

The type of selected items. value or text

The default is value.

alert('Selected values: ' + $('select').multipleSelect('getSelects'));
alert('Selected texts: ' + $('select').multipleSelect('getSelects', 'text'));

setSelects

Sets the selected values.

Parameter: values

Type: array

The values of selected items.

$('select').multipleSelect('setSelects', [1, 3]);

enable

Enables Select.

$('select').multipleSelect('enable');

disable

Disables Select. During this mode the user is not allowed to manipulate the selection.

$('select').multipleSelect('disable');

checkAll

Check all checkboxes.

$('select').multipleSelect('checkAll');

uncheckAll

Uncheck all checkboxes.

$('select').multipleSelect('uncheckAll');

focus

Focus the multiple select.

$('select').multipleSelect('focus');

blur

Blur the multiple select.

$('select').multipleSelect('blur');

refresh

Reloads the Multiple Select.

If you're dynamically adding/removing option tags on the original select via AJAX or DOM manipulation methods, call refresh to reflect the changes.

$('select').multipleSelect('refresh');

About

blog

scutech

Acknowledgements

My website (wenzhixin.net.cn)

Github (@wenzhixin)

Weibo (@文翼)

Email ([email protected])

Name		Name	Last commit message	Last commit date
parent directory ..
assets		assets
css		css
js		js
README-ZH-CN.md		README-ZH-CN.md
README.md		README.md
index.html		index.html

FilesExpand file tree

docs

Directory actions

More options

Directory actions

More options

Latest commit

History

docs

Folders and files

parent directory

README.md

Multiple Select

Requirements

Features

Browser Compatibility

Examples

The Basics1

The Basics2

The Basics3

With Optgroups1

With Optgroups2

The Placeholder

The Multiple Items

With Optgroups

The Hide Select All

The Single Row

The Position

The Filter1

The Filter2

The Keep Open

The Styler

SetSelects/GetSelects

Enable/Disable

CheckAll/UncheckAll

Focus/Blur

The Refresh

The Callbacks/Events

Documentation

Constructor

isOpen

placeholder

selectAll

selectAllText

selectAllDelimiter

allSelected

minimumCountSelected

countSelected

ellipsis

multiple

multipleWidth

single

position

filter

width

maxHeight

keepOpen

styler

Events

onOpen

onClose

onCheckAll

onUncheckAll

onFocus

onBlur

onOptgroupClick

onClick

Methods

getSelects

setSelects

enable

disable

checkAll

uncheckAll

focus

blur

refresh

About

Acknowledgements