-
Notifications
You must be signed in to change notification settings - Fork 692
Options
(In alphabetical order.)
addInputNames
A boolean value denoting whether or not to automatically create names for each option input in the multi-select.
Default: true
appendTo
Selector for the element under which the multiselect elements should be added. This option follows the jQuery UI recommended stacking order. If a dialog or .ui-front is found in the widget's ancestors, the menu will append to that element. Otherwise it will append to the body. Setting this option will override that behavior.
Note: If you are seeing a truncated menu, explicitly set this option to document.body.
Default: null
autoOpen
A boolean value denoting whether or not to automatically open the menu when the widget is initialized.
Default: false
buttonWidth
A numeric or string value directly or indirectly specifying the width of the main widget button.
- If null is specified, the button width will match the width of the native select element.
- If a numeric value is specified, it is assumed that the units are pixels.
- If a string value containing a number is specified, the value is checked for one of several accepted units (px, pt, em, in, cm, mm, or %) following the number, and the value is converted to pixels internally.
- If a string is specified that starts with
>=/>or<=/<, the value is assumed to be a minimum or maximum value, respectively, that is compared against the width of the native select element. - If "auto" is specified, the width will be set to 'auto' and will automatically adjust to fit the button's container.
Note: This option is ignored if the listbox option is set to true.
Default: 225
classes
Additional class(es) to apply to BOTH the button and menu for further customization. Separate multiple classes with a space. You'll need to scope your CSS to differentiate between the button & menu:
/* button styling with custom class name*/
.ui-multiselect.myClass {}
/* menu styling with custom class name */
.ui-multiselect-menu.myClass {}
Default: Empty string
closeEffect
The name of the effect to use when the menu closes. To control the speed as well, pass in an array: ['explode', 500]
Default: Empty string
disableInputsOnToggle
Determines if all option inputs should be disabled when the widget is disabled.
Default: true
groupsCollapsable
A boolean true / false value that determines if clicking on an option group heading collapses the option group and hides all of its options.
Default: false
groupColumns
Determines if option groups will be displayed as columns instead of rows.
Default: false
groupsSelectable
A boolean true / false value that determines if clicking on an option group heading selects all of its options.
Default: true
header
One of the following:
- An array of link identifiers to show in the header in the order that they should be displayed (e.g.,
['checkAll','uncheckAll']) - A custom string that is displayed in the header instead of any links.
- The boolean value
false. No header is displayed.
Valid link identifiers for the header are: checkAll, uncheckAll, flipAll, collapseAll, or expandAll
Default: ['checkAll','uncheckAll']
htmlText
This option allows you to provide an array of keywords to specify in which parts of the widget ('button' &/or 'options') that the text be treated as html.
Default: []
linkInfo
A plain object that allows link customization information to be specified. The structure of the object is similar to the linkDefaults object in the widget code. Generally, it is a nested object:
{
link_key_1: {icon: 'myicon1', text: 'mytext1', title: 'mytitle1'},
link_key_2: {icon: 'myicon2', text: 'mytext2', title: 'mytitle2'},
...
etc.
}
The recognized link keys are the following: open, close, checkAll, uncheckAll, flipAll, collapse, expand, collapseAll, and expandAll.
Note: Because the supplied object is merged with the internal linkDefaults object via an $.extend(), you only need to specify the items in the settings option to be changed from the default.
Refer to the Customization wiki for a detailed description of how to use this option.
Default: null
listbox
A boolean value that causes the widget to omit the button and instead of a pop-up inserts the open menu directly after the native select as a list box.
Default: false
maxSelected
An integer value may be specified. If the current count of selections is greater than maxSelected when a new selection is made, then a message is displayed, and the new selection is undone.
Default: null
menuHeight
A numeric or string value directly or indirectly specifying the height of the checkbox container (scroll area).
- If a numeric value is specified, it is assumed that the units are pixels.
- If a string value containing a number is specified, the value is checked for one of several accepted units (px, pt, em, in, cm, mm, or %) following the number, and the value is converted to pixels internally.
- If "auto" or null is specified, the height will be calculated based on the number of check boxes in the menu.
- If the option is set to "size", the size attribute of the native select element will be used for the number of rows to show.
Note: The menu height is limited to the visible area in the container window.
Default: 175
menuWidth
A numeric or string value directly or indirectly specifying the width of the menu displayed after the button is clicked. Useful if you have long text options or there was limited space for the select.
- If null is specified, the menu width will match the button width.
- If a numeric value is specified, it is assumed that the units are pixels.
- If a string value containing a number is specified, the value is checked for one of several accepted units (px, pt, em, in, cm, mm, or %) following the number, and the value is converted to pixels internally.
- If a string is specified that starts with
>=/>or<=/<, the value is assumed to be a minimum or maximum value, respectively, that is compared against the button width. - If "auto" is specified, a "best fit width" will be determined for the menu.
Default: null (Default matches the button width.)
noneSelectedText
The default text the select box when no options have been selected.
Default: "Select options"
openEffect
The name of the effect to use when the menu opens. To control the speed as well, pass in an array: ['slide', 500]
Default: Empty string
position
This option allows you to position the menu anywhere you'd like relative to the button; centered, above, below (default), etc. Also provides collision detection to flip the menu above the button when near the bottom of the window. If you do not set this option or if the position utility has not been included, the menu will open below the button. Requires the jQuery UI position utility and jQuery 1.4.3+. Please see this demo for usage instructions.
Default: {}
Note: This is merged with {my: 'left top', at: 'left bottom', of: $button} internally via $.extend() to produce a "working position object".
resizableMenu
A boolean value that makes the menu vertically resizable if jQuery UI resizable is loaded.
Default: false
selectedList
A numeric (or boolean to disable) value denoting whether or not to display the checked opens in a list, and how many. A number greater than 0 denotes the maximum number of list items to display before switching over to the selectedText parameter. A value of 0 or false is disabled.
Default: false
selectedListSeparator
Sets the separator text used to separate selected items shown in the button text.
Default: ", "
selectedText
The text to display in the select box when options are selected (if selectedList is false). A pound sign (#) will automatically replaced by the number of checkboxes selected. If two pound signs are present in this parameter, the second will be replaced by the total number of checkboxes available.
Example: "# of # checked".
This parameter also accepts an anonymous function with three arguments: the number of checkboxes checked, the total number of checkboxes, and an array of the checked checkbox DOM elements. See examples for usage.
Default: "# of # selected"
wrapText
List of 'button', 'header', &/or 'options' indicating in which parts of the widget to wrap text.
Default: ['button','header','options']
zIndex
Overrides the z-index set for the menu container. Typically, the widget will automatically determine the best z-index, but it may be necessarily to override it for edge cases.
Default: null