A dropdown can be used to select between choices in a form
Selection dropdowns can be initialized directly on a select or with the matching HTML and a hidden input.
A selection dropdown can allow a user to search through a large list of choices.
A selection dropdown can allow multiple selections
A selection dropdown can allow multiple search selections
Dropdowns can support content that may not be allowed inside option tags when converting select elements. For more complex content like flags or icons you can use full dropdown markup
A dropdown can be searchable
A dropdown can include a search prompt inside its menu
A dropdown can be formatted to appear inline in other content
Show me posts by
A dropdown can be formatted so that its menu is pointing
Bottom pointing dropdown menus have sub-menus open upwards
A dropdown menu can appear to be floating below an element.
A simple dropdown can open without Javascript
A dropdown menu can contain a header
A dropdown menu can contain dividers to separate related content
A dropdown menu can contain an icon.
A dropdown menu can contain a description.
Using a description may require setting a minimum width on menu to prevent content overlap
A dropdown menu can contain a label.
A dropdown menu can contain a message.
A dropdown menu can contain floated content.
Floated content may stack to two lines without manually setting a width when or using a fluid dropdown
A dropdown menu can contain an input
A dropdown menu can contain an image
A dropdown can show that it is currently loading data
An errored dropdown can alert a user to a problem
An active dropdown has its menu open
An active state will only automatically open a ui simple dropdown. To activate a normal dropdown use $('.ui.dropdown').dropdown('show');
A disabled dropdown menu or item does not allow user interaction
A dropdown can have its menu scroll
Scrolling dropdowns are incompatible with the usage of sub menu.
A compact dropdown has no minimum width
A dropdown can take the full width of its parent
A dropdown menu or sub-menu can specify the direction it should open
Specifying left on a menu will make all child menus open in the same direction implicitly. To have a dropdown icon appear on the left side on a child menu, you will need to use left dropdown example
Using the clearable setting will let users remove their selection from a dropdown.
Show me
classes currently available.
$('.clearable.example .ui.selection.dropdown') .dropdown({ clearable: true }) ; $('.clearable.example .ui.inline.dropdown') .dropdown({ clearable: true, placeholder: 'any' }) ;
Using maxSelections lets you force a maximum number of selections. You can also use form validation rules to specify minimum and maximum validation settings for multi-selects inside forms.
$('.max.example .ui.normal.dropdown') .dropdown({ maxSelections: 3 }) ; $('.max.example .ui.special.dropdown') .dropdown({ useLabels: false, maxSelections: 3 }) ;
Using allowAdditions: true gives users the ability to add their own options. This can work with either single or multiple search select dropdowns
Although all dropdowns support select initialization, custom choices will not be saved on page refresh unless you use a hidden input. This is because option created dynamically are not preserved on page refresh.
$('.tag.example .ui.dropdown') .dropdown({ allowAdditions: true }) ;
Sometimes multiselect include options which are long and would appear awkwardly as labels. Setting useLabels: false will display a selected count, and allow reselection directly from the menu.
You can customize any of the messages displayed by adjusting templates in settings.message
or
$('.no.label.example .ui.dropdown') .dropdown({ useLabels: false }) ;
You can reset a form field to its placeholder value
Clear
$('.clear.example .button') .on('click', function() { $('.clear.example .ui.dropdown') .dropdown('clear') ; }) ;
You can restore a dropdown to its value set on page load using the restore defaults behavior. If no default text is set on load, restore defaults will restore placeholder text
Restore All Dropdowns
$('.restore.example .button') .on('click', function() { $('.restore.example .ui.dropdown') .dropdown('restore defaults') ; }) ;
A dropdown menu will automatically change which direction it opens if it can't fit on screen. If you need a dropdown to open in a specific direction you can specify it when initializing a dropdown.
$('.upward.example .dropdown') .dropdown({ direction: 'upward' }) ;
Search selection dropdowns can specify API settings for retrieving values remotely, this can use either a named API action or url.
Using API can allow users to select choices from large datasets that would be too large to include directly in page markups.
If your backend is not designed to return the correct markup you can use API's onResponse callback to adjust the format of an API response after it is received from the server.
Requests for the same API endpoints will automatically cached locally, to avoid server roundtrips. You can disable this by adjusting the cache API setting.
When a user refreshes the page, selection labels are automatically recreated by using sessionStorage to store the corresponding names for selected values. You can disable this feature by setting saveRemoteData: false
$('.remote.filter.example .ui.dropdown') .dropdown({ apiSettings: { // this url parses query server side and returns filtered results url: '//api.semantic-ui.com/tags/{query}' }, }) ;
// Expected server response { "success": true, "results": [ { // name displayed in dropdown "name" : "Choice 1", // selected value "value" : "value1", // name displayed after selection (optional) "text" : "Choice 1" // whether field should be displayed as disabled (optional) "disabled" : false }, { "name" : "Choice 2", "value" : "value2", "text" : "Choice 2" }, { "name" : "Choice 3", "value" : "value3", "text" : "Choice 3" }, { "name" : "Choice 4", "value" : "value4", "text" : "Choice 4" }, { "name" : "Choice 5", "value" : "value5", "text" : "Choice 5" } ] }
When possible choicesets are large, ideally API results should only return values matching the passed query term to reduce transmissions over the wire. However if there are only a few hundred or less choices, you may consider returning the full set of results from an API endpoint and filtering them against the query clientside using the setting filterRemoteData: true.
$('.remote.choices.example .ui.dropdown') .dropdown({ apiSettings: { // this url just returns a list of tags (with API response expected above) url: '//api.semantic-ui.com/tags/' }, filterRemoteData: true }) ;
A dropdown can specify a different transition.
$('.dropdown') .dropdown({ // you can use any ui transition transition: 'drop' }) ;
A dropdown menu can also contain sub menus inside of it
My favorite animal breed is
Using a multi-level menu with allowCategorySelection: true will allow items with sub-menus to be selected.
$('.category.example .ui.dropdown') .dropdown({ allowCategorySelection: true }) ;
This example uses a preset text value to preserve the menu item on page navigation
A dropdown will automatically select on page load any menu item that includes the current value of text or your dropdown's hidden input value.
This is used to preserve a user's selection on page navigation and will automatically remove and default text placeholder formatting.
Current action:
A button can be formatted with a dropdown.
Using the combo action will change the preceding element to the selected value.
$('.combo.dropdown') .dropdown({ action: 'combo' }) ;
Dropdowns support different default actions that can occur when an item is selected. For example, you can set your dropdown not to change its text, or select a value from its menu.
$('.link.example .dropdown') .dropdown({ action: 'hide' }) ;
A button group can be formatted to show additional content as a dropdown
A menu element can contain a dropdown
A dropdown can be formatted to allow selection inside a form
Initializing a dropdown with pre-existing HTML allows for greater performance than initializing a dropdown directly on a select element.
Any select element initialized as dropdown will also be hidden until Javascript can create HTML, this is to avoid the flash of unstyled content, and the change in element height adjusting page flow.
$('.ui.dropdown') .dropdown() ;
You can specify a list of values in the settings object to avoid having to stub the html yourself.
Adding selected: true to an item will have that item selected by default.
You can also use the placeholder setting to specify placeholder text before an option is selected.
$('.ui.dropdown') .dropdown({ values: [ { name: 'Male', value: 'male' }, { name : 'Female', value : 'female', selected : true } ] }) ;
You can specify different values for selected text, and selected form values by adding data-text or data-value to any item. This is useful if you include additional data, like icons, that you want to appear only inside the dropdown menu.
If you don't specify a value (either in the `select` or via a `data-value` property, then the input value will be set to the lowercased text in the element.
For convenience, select elements can automatically be converted to selection dropdown. A select options with blank string values will be converted to prompt text.
$('#select') .dropdown() ;
As a third option, you can include a wrapper around your select so that it will appear correctly on page load, but will then populate the hidden menu when Javascript fires. In this case, the select element does not receive the ui dropdown class.
$('#hybrid select') .dropdown({ on: 'hover' }) ;
Using a search selection dropdown will allow you users to search more easily through large lists. This can also be converted directly from a form select element.
$('#search-select') .dropdown() ;
You can allow multiple selections by the multiple property on a select element, or by including the class multiple on a dropdown.
When pre-existing HTML with a hidden input is used, values will be passed through a single value separated by a delimiter. The default is "," but this can be changed by adjusting the delimiter setting.
$('#multi-select') .dropdown() ;
Dropdowns have multiple built-in actions that can occur on item selection. You can specify a built-in action by passing its name to settings.action or pass a custom function that performs an action.
activate (Default) | Selects current item, adjusts dropdown value and changes dropdown text |
combo | Same as activate, but updates previous elements text instead of self |
select | Selects current item from menu and stores value, but does not change dropdown text |
hide | Hides the dropdown menu and stores value, but does not change text |
function(text, value){} | Custom action |
nothing | Does nothing |
To specify a different built in action, simply specify the name.
$('.dropdown') .dropdown({ action: 'combo' }) ;
To trigger only your custom action and no default action, specify your own function for settings.action.
$('.dropdown') .dropdown({ action: function(text, value) { // nothing built in occurs } }) ;
If you want to have both a built in action occur, and your own custom action use onChange in combination with action
$('.dropdown') .dropdown({ action: 'hide', onChange: function(value, text, $selectedItem) { // custom action } }) ;
All the following behaviors can be called using the syntax:
$('.your.element') .dropdown('behavior name', argumentOne, argumentTwo) ;
setup menu(values) | Recreates dropdown menu from passed values. values should be an object with the following structure: { values: [ {value, text, name} ] }. |
change values (values) | Changes dropdown to use new values |
refresh | Refreshes all cached selectors and data |
toggle | Toggles current visibility of dropdown |
show | Shows dropdown |
hide | Hides dropdown |
clear | Clears dropdown of selection |
hide others | Hides all other dropdowns that is not current dropdown |
restore defaults | Restores dropdown text and value to its value on page load |
restore default text | Restores dropdown text to its value on page load |
restore placeholder text | Restores dropdown text to its prompt, placeholder text |
restore default value | Restores dropdown value to its value on page load |
save defaults | Saves current text and value as new defaults (for use with restore) |
set selected(value) | Sets value as selected |
remove selected(value) | Remove value from selected |
set selected([value1, value2]) | Adds a group of values as selected |
set exactly([value1, value2]) | Sets selected values to exactly specified values, removing current selection |
set text(text) | Sets dropdown text to a value |
set value(value) | Sets dropdown input to value (does not update display state) |
get text | Returns current dropdown text |
get value | Returns current dropdown input value |
get item(value) | Returns DOM element that matches a given input value |
bind touch events | Adds touch events to element |
bind mouse events | Adds mouse events to element |
bind intent | Binds a click to document to determine if you click away from a dropdown |
unbind intent | Unbinds document intent click |
determine intent | Returns whether event occurred inside dropdown |
determine select action(text, value) | Triggers preset item selection action based on settings passing text/value |
set active | Sets dropdown to active state |
set visible | Sets dropdown to visible state |
remove active | Removes dropdown active state |
remove visible | Removes dropdown visible state |
is selection | Returns whether dropdown is a selection dropdown |
is animated | Returns whether dropdown is animated |
is visible | Returns whether dropdown is visible |
is hidden | Returns whether dropdown is hidden |
get default text | Returns dropdown value as set on page load |
get placeholder text | Returns placeholder text |
values | false | When specified allows you to initialize dropdown with specific values. See usage guide for details. |
on | click | Event used to trigger dropdown (Hover, Click, Custom Event) |
clearable | false | Whether the dropdown value can be cleared by the user after being selected. |
ignoreCase | false New in 2.2.13 | Whether values with matching cases should be treated as identical when adding them to a dropdown. |
allowReselection | false | When set to true will fire onChange even when the value a user select matches the currently selected value. |
allowAdditions | false | Whether search selection should allow users to add their own selections, works for single or multiselect. |
hideAdditions | true | If disabled user additions will appear in the dropdown's menu using a specially formatted selection item formatted by templates.addition. |
action | auto | Sets a default action to occur. (See usage guide) Updates dropdown text with selected value, sets element state to active, updates any hidden fields if available activates menu and updates input fields, but does not change current text changes text of previous sibling element no action occurs Dropdown menu is hidden custom function is executed with values specified in callback |
minCharacters | 1 | The minimum characters for a search to begin showing results |
match | both | When using search selection specifies how to match values. Matches against text and value matches against value only matches against text only |
selectOnKeydown | true | Whether dropdown should select new option when using keyboard shortcuts. Setting to false will require enter or left click to confirm a choice. |
forceSelection | true | Whether search selection will force currently selected choice when element is blurred. |
allowCategorySelection | false | Whether menu items with sub-menus (categories) should be selectable |
placeholder | auto | Convert option with "" (blank string) value to placeholder text Sets string value to placeholder text, leaves "" value Leaves "" value as a selectable option |
apiSettings | false | Can be set to an object to specify API settings for retrieving remote selection menu content from an API endpoint |
fields | fields: { remoteValues : 'results', // grouping for api results values : 'values', // grouping for all dropdown values name : 'name', // displayed dropdown text value : 'value' // actual dropdown value } | List mapping dropdown content to JSON Property when using API |
filterRemoteData | false | Whether results returned from API should be filtered by query before being displayed |
saveRemoteData | true | When enabled, will automatically store selected name/value pairs in sessionStorage to preserve user selection on page refresh. Disabling will clear remote dropdown values on refresh. |
useLabels | true | Whether multiselect should use labels. Must be set to true when allowAdditions is true |
maxSelections | false | When set to a number, sets the maximum number of selections |
glyphWidth | 1.0714 | Maximum glyph width, used to calculate search size. This is usually size of a "W" in your font in em |
label | label: { transition : 'horizontal flip', duration : 200, variation : false } | Allows customization of multi-select labels |
direction | 'auto' | When set to auto determines direction based on whether dropdown can fit on screen. Set to upward or downward to always force a direction. |
keepOnScreen | true | Whether dropdown should try to keep itself on screen by checking whether menus display position in its context (Default context is page). |
context | window | Element context to use when checking whether can show when keepOnScreen: true |
fullTextSearch | false | Specifying to "true" will use a fuzzy full text search, setting to "exact" will force the exact search to be matched somewhere in the string, setting to "false" will only match start of string. |
preserveHTML | true | Whether HTML included in dropdown values should be preserved. (Allows icons to show up in selected value) |
sortSelect | false | Whether to sort values when creating a dropdown automatically from a select element. |
showOnFocus | true | Whether to show dropdown menu automatically on element focus. |
allowTab | true | Whether to allow the element to be navigable by keyboard, by automatically creating a tabindex |
transition | auto (slide down / slide up) | Named transition to use when animating menu in and out. Defaults to slide down or slide up depending on dropdown direction. Fade and slide down are available without including ui transitions |
duration | 200 | Duration of animation events |
keys | keys : { backspace : 8, delimiter : 188, // comma deleteKey : 46, enter : 13, escape : 27, pageUp : 33, pageDown : 34, leftArrow : 37, upArrow : 38, rightArrow : 39, downArrow : 40 } | The keycode used to represent keyboard shortcuts. To avoid issues with some foreign languages, you can pass false for comma delimiter's value |
delay | delay : { hide : 300, show : 200, search : 50, touch : 50 } | Time in milliseconds to debounce show or hide behavior when on: hover is used, or when touch is used. |
onChange(value, text, $choice) | Dropdown | Is called after a dropdown value changes. Receives the name and value of selection and the active menu element |
onAdd(addedValue, addedText, $addedChoice) | Dropdown | Is called after a dropdown selection is added using a multiple select dropdown, only receives the added value |
onRemove(removedValue, removedText, $removedChoice) | Dropdown | Is called after a dropdown selection is removed using a multiple select dropdown, only receives the removed value |
onLabelCreate(value, text) | $label (jQDOM) | Allows you to modify a label before it is added. Expects the jQ DOM element for a label to be returned. |
onLabelRemove(value) | $label (jqDOM) | Called when a label is remove, return false; will prevent the label from being removed. |
onLabelSelect($selectedLabels) | Dropdown | Is called after a label is selected by a user |
onNoResults(searchValue) | Dropdown | Is called after a dropdown is searched with no matching values |
onShow | Dropdown | Is called before a dropdown is shown. If false is returned, dropdown will not be shown. |
onHide | Dropdown | Is called before a dropdown is hidden. If false is returned, dropdown will not be hidden. |
namespace | dropdown | Event namespace. Makes sure module teardown does not effect other events attached to an element. |
message | You can specify site wide messages by modifying $.fn.dropdown.settings.message that will apply on any dropdown if it appears in the page. message: { addResult : 'Add {term}', count : '{count} selected', maxSelections : 'Max {maxCount} selections', noResults : 'No results found.' } | |
selector | selector : { addition : '.addition', dropdown : '.ui.dropdown', icon : '> .dropdown.icon', input : '> input[type="hidden"], > select', item : '.item', label : '> .label', remove : '> .label > .delete.icon', siblingLabel : '.label', menu : '.menu', message : '.message', menuIcon : '.dropdown.icon', search : 'input.search, .menu > .search > input', text : '> .text:not(.icon)' } | |
regExp | regExp : { escape : /[-[\]{}()*+?.,\\^$|#\s]/g, } | |
metadata | metadata : { defaultText : 'defaultText', defaultValue : 'defaultValue', placeholderText : 'placeholderText', text : 'text', value : 'value' } | |
className | className : { active : 'active', addition : 'addition', animating : 'animating', disabled : 'disabled', dropdown : 'ui dropdown', filtered : 'filtered', hidden : 'hidden transition', item : 'item', label : 'ui label', loading : 'loading', menu : 'menu', message : 'message', multiple : 'multiple', placeholder : 'default', search : 'search', selected : 'selected', selection : 'selection', upward : 'upward', visible : 'visible' } | |
name | Dropdown | Name used in debug logs |
silent | False | Silences all console output including error messages, regardless of other debug settings. |
debug | False | Provides standard debug output to console |
performance | True | Provides performance stats in console, and suppresses other debug output. |
verbose | True | Provides ancillary debug output to console |
error | error : { action : 'You called a dropdown action that was not defined', alreadySetup : 'Once a select has been initialized behaviors must be called on the created ui dropdown', labels : 'Allowing user additions currently requires the use of labels.', method : 'The method you called is not defined.', noTransition : 'This module requires ui transitions ' } |