DropDown
Drop-down UI component
Description
A drop-down UI component allows an app user to select an option or type in text.
Use the DropDown object to modify the appearance and behavior of a drop-down
list after you create it.
Creation
Create a drop-down list in an app using the uidropdown function.
Properties
Drop-Down
Index of the component value in the list of items or item data, specified as a positive integer.
In most cases, you can use the Value property to query and
update the component value. However, the ValueIndex property can
be useful when both the Items and ItemsData
properties are nonempty. In this case, you can use the ValueIndex
property to query the element of Items that corresponds to the
current
value.
fig = uifigure; dd = uidropdown(fig, ... "Items",["Red","Green","Blue"], ... "ItemsData",["#F00","#0F0","#00F"]); idx = dd.ValueIndex; disp(dd.Items(idx) + ": " + dd.Value)
Red: #F00
When the Editable property of the drop-down component is set
to 'on', you can additionally specify
ValueIndex as an empty array ([]).
MATLAB sets the ValueIndex property to an empty array when
an app user types a value into the component that does not correspond to an item in
Items. If you set ValueIndex to an empty
array, MATLAB sets the Value property to
''.
Placeholder text, specified as a character vector or string scalar. The
placeholder provides a short description of the drop-down items. The placeholder text
appears only when the drop-down component displays ''. There are
two situations where this happens:
The
Valueproperty is set to''.The
Valueproperty is set to an element ofItemsDatawhose corresponding item is''.
For example, to display a placeholder in a drop-down component with no
ItemsData, add '' to Items
and set the Value property to '':
fig = uifigure('Position',[100 100 300 200]); dd = uidropdown(fig,'Items',{'','One','Two'}, ... 'Value','', ... 'Placeholder','Options');
Font and Color
Font color, specified as an RGB triplet, a hexadecimal color code, or one of the options listed in the table.
RGB triplets and hexadecimal color codes are useful for specifying custom colors.
An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range
[0,1]; for example,[0.4 0.6 0.7].A hexadecimal color code is a character vector or a string scalar that starts with a hash symbol (
#) followed by three or six hexadecimal digits, which can range from0toF. The values are not case sensitive. Thus, the color codes"#FF8800","#ff8800","#F80", and"#f80"are equivalent.
Alternatively, you can specify some common colors by name. This table lists the named color options, the equivalent RGB triplets, and hexadecimal color codes.
| Color Name | Short Name | RGB Triplet | Hexadecimal Color Code | Appearance |
|---|---|---|---|---|
"red" | "r" | [1 0 0] | "#FF0000" |
|
"green" | "g" | [0 1 0] | "#00FF00" |
|
"blue" | "b" | [0 0 1] | "#0000FF" |
|
"cyan"
| "c" | [0 1 1] | "#00FFFF" |
|
"magenta" | "m" | [1 0 1] | "#FF00FF" |
|
"yellow" | "y" | [1 1 0] | "#FFFF00" |
|
"black" | "k" | [0 0 0] | "#000000" |
|
"white" | "w" | [1 1 1] | "#FFFFFF" |
|
This table lists the default color palettes for plots in the light and dark themes.
| Palette | Palette Colors |
|---|---|
Before R2025a: Most plots use these colors by default. |
|
|
|
You can get the RGB triplets and hexadecimal color codes for these palettes using the orderedcolors and rgb2hex functions. For example, get the RGB triplets for the "gem" palette and convert them to hexadecimal color codes.
RGB = orderedcolors("gem");
H = rgb2hex(RGB);Before R2023b: Get the RGB triplets using RGB =
get(groot,"FactoryAxesColorOrder").
Before R2024a: Get the hexadecimal color codes using H =
compose("#%02X%02X%02X",round(RGB*255)).
Background color, specified as an RGB triplet, a hexadecimal color code, or one of the color options listed in the table.
RGB triplets and hexadecimal color codes are useful for specifying custom colors.
An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range
[0,1]; for example,[0.4 0.6 0.7].A hexadecimal color code is a character vector or a string scalar that starts with a hash symbol (
#) followed by three or six hexadecimal digits, which can range from0toF. The values are not case sensitive. Thus, the color codes"#FF8800","#ff8800","#F80", and"#f80"are equivalent.
Alternatively, you can specify some common colors by name. This table lists the named color options, the equivalent RGB triplets, and hexadecimal color codes.
| Color Name | Short Name | RGB Triplet | Hexadecimal Color Code | Appearance |
|---|---|---|---|---|
"red" | "r" | [1 0 0] | "#FF0000" |
|
"green" | "g" | [0 1 0] | "#00FF00" |
|
"blue" | "b" | [0 0 1] | "#0000FF" |
|
"cyan"
| "c" | [0 1 1] | "#00FFFF" |
|
"magenta" | "m" | [1 0 1] | "#FF00FF" |
|
"yellow" | "y" | [1 1 0] | "#FFFF00" |
|
"black" | "k" | [0 0 0] | "#000000" |
|
"white" | "w" | [1 1 1] | "#FFFFFF" |
|
This table lists the default color palettes for plots in the light and dark themes.
| Palette | Palette Colors |
|---|---|
Before R2025a: Most plots use these colors by default. |
|
|
|
You can get the RGB triplets and hexadecimal color codes for these palettes using the orderedcolors and rgb2hex functions. For example, get the RGB triplets for the "gem" palette and convert them to hexadecimal color codes.
RGB = orderedcolors("gem");
H = rgb2hex(RGB);Before R2023b: Get the RGB triplets using RGB =
get(groot,"FactoryAxesColorOrder").
Before R2024a: Get the hexadecimal color codes using H =
compose("#%02X%02X%02X",round(RGB*255)).
This property is read-only.
Configuration of added styles created using the uistyle
function, returned as an n-by-3 table array. Each row of the table
array corresponds to a style that is currently applied to the drop-down component.
Styles that are added consecutively are given a style order number of
n+1. The Target and
TargetIndex columns specify the part of the component that the
style was added to. The Style column specifies the style class
name.
Use this property if you want to remove a style from the drop-down component using
the removeStyle function.
Example: Remove a Style
First, add two styles to a drop-down component.
fig = uifigure; fig.Position = [100 100 300 250]; dd = uidropdown(fig); s1 = uistyle("FontColor","blue"); s2 = uistyle("FontColor","red"); addStyle(dd,s1,"item",1); addStyle(dd,s2,"item",[2 3 4]);
When you query dd.StyleConfigurations, MATLAB returns a 2-by-3 table array. The blue font style was added to the
component first, so it is style order number 1. The
TargetIndex value for the level style,
{[1]}, indicates that the style was applied to the first item in
the component. Similarly, the second style was added to the last three items in the
component
dd.StyleConfigurations
ans =
2×3 table
Target TargetIndex Style
______ ___________ _________________________
1 item {[ 1]} 1×1 matlab.ui.style.Style
2 item {[2 3 4]} 1×1 matlab.ui.style.Style
Remove the second style that was added to the drop-down component by specifying
style order number 2. The component appearance updates to use
only the first style.
removeStyle(dd,2)
Interactivity
Tooltip, specified as a character vector, cell array of character vectors, string array, or 1-D categorical array. Use this property to display a message when the user hovers the pointer over the component at run time. The tooltip displays even when the component is disabled. To display multiple lines of text, specify a cell array of character vectors or a string array. Each element in the array becomes a separate line of text. If you specify this property as a categorical array, MATLAB uses the values in the array, not the full set of categories.
Context menu, specified as a ContextMenu object created using the uicontextmenu function. Use this property to display a context menu when
you right-click on a component.
Position
Inner location and size of the drop-down component, specified as [left
bottom width height]. Position values are relative to the parent
container. All measurements are in pixel units. This property value is identical to
Position for drop-down components.
This property is read-only.
Outer location and size of drop-down component returned as [left bottom
width height]. Position values are relative to the parent container. All
measurements are in pixel units. This property value is identical to
Position for drop-down components.
Layout options, specified as a
GridLayoutOptions object. This property specifies options for
components that are children of grid layout containers. If the component is not a
child of a grid layout container (for example, it is a child of a figure or panel),
then this property is empty and has no effect. However, if the component is a child of
a grid layout container, you can place the component in the desired row and column of
the grid by setting the Row and Column
properties on the GridLayoutOptions object.
For example, this code places a drop-down in the third row and second column of its parent grid.
g = uigridlayout([4 3]); dd = uidropdown(g); dd.Layout.Row = 3; dd.Layout.Column = 2;
To make the drop-down span multiple rows or columns, specify the
Row or Column property as a two-element
vector. For example, this drop-down spans columns 2 through
3:
dd.Layout.Column = [2 3];
Callbacks
Drop-down menu opening callback, specified as one of these values:
A function handle.
A cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.
A character vector containing a valid MATLAB expression (not recommended). MATLAB evaluates this expression in the base workspace.
This property specifies a callback function to execute when the user clicks to open the drop-down menu. A possible use for this callback is to dynamically update the list of entries in the drop-down menu.
This callback function can access specific information about the user’s interaction
with the drop-down. MATLAB passes this information in a DropDownOpeningData object as the second argument to your callback
function. In App Designer, the argument is called event. You can
query the object properties using dot notation. For example,
event.Source returns the DropDown object that
the user interacts with to trigger the callback. The DropDownOpeningData object is not available to callback functions
specified as character vectors.
The following table lists the properties of the DropDownOpeningData object.
| Property | Value |
|---|---|
Source | Component that executes the callback |
EventName | 'DropDownOpening' |
For more information about writing callbacks, see Callbacks in App Designer.
Clicked callback, specified as one of these values:
A function handle.
A cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.
A character vector containing a valid MATLAB expression (not recommended). MATLAB evaluates this expression in the base workspace.
This callback function executes when the user clicks anywhere in the drop-down component.
This callback function can access specific information about the user’s
interaction with the drop-down component. MATLAB passes this information in a ClickedData object as the second argument to your callback function. In
App Designer, the argument is called event. You can query the
object properties using dot notation. For example,
event.InteractionInformation returns information about where the
user clicked in the drop-down component. The ClickedData object is not available to callback functions specified as
character vectors.
This table lists the properties of the ClickedData object.
| Property | Value |
|---|---|
InteractionInformation | Information about where in the component the app user clicked. This information is stored as an object with these properties:
You can query the object properties using dot notation. For
example, |
Source | Component that executes the callback |
EventName | 'Clicked' |
This table lists the properties of the InteractionInformation object associated with the drop-down
component.
| Property | Value |
|---|---|
Item | Index of the clicked drop-down component item, returned as a scalar. If the user clicked an area of the drop-down component
that is not associated with an item, then |
Location | Location where the user clicked relative to the bottom-left corner
of the drop-down component parent container, returned as a two-element
vector of the form The value of
|
ScreenLocation | Location where the user clicked relative to the bottom-left corner
of their primary display, returned as a two-element vector of the form
The value of |
For more information about writing callbacks, see Callbacks in App Designer.
Example: Display Data When Drop-Down Component Is Clicked
Create a drop-down component with items that represent groceries and item data
that represents their cost. Specify a ClickedFcn callback
function named displayCost that executes when a user clicks the
component. In the displayCost function:
Use the
event.InteractionInformationobject to access information about whether the user clicked an item.If the user did click an item (as opposed to a location in the drop-down component that is not associated with an item), query the item and its cost.
Display the item and its cost in the Command Window.
To try this example, save the code in a new script and run it. Click an item in the drop-down component to display its cost.
fig = uifigure; dd = uidropdown(fig); dd.Items = ["Apple","Banana","Orange"]; dd.ItemsData = [1.2,0.5,1.2]; dd.ClickedFcn = @displayCost; function displayCost(dd,event) idx = event.InteractionInformation.Item; if ~isempty(idx) fruit = dd.Items(idx); cost = dd.ItemsData(idx); disp(fruit + " cost $" + cost) end end
Callback Execution Control
Parent/Child
Parent container, specified as a Figure object or
one of its child containers: Tab, Panel, ButtonGroup, or
GridLayout. If no container is specified,
MATLAB calls the uifigure function to create a new Figure object that serves as the parent container.
Identifiers
This property is read-only.
Type of graphics object, returned as 'uidropdown'.
Object Functions
addStyle | Add style to UI component |
removeStyle | Remove style from UI component |
focus | Give focus to UI component |
Examples
Create a drop-down component in a UI figure and specify the items.
fig = uifigure; dd = uidropdown(fig,"Items",["Red","Yellow","Blue","Green"]);
Determine the value associated with the selected item. When the
ItemsData property is empty (the default), the drop-down
component Value property stores the name of the selected item as it
appears in the Items property.
value = dd.Value
value =
'Red'Associate a hexadecimal color code with each drop-down component item by specifying
the ItemsData property.
dd.ItemsData = ["#F00" "#FF0" "#00F" "#0F0"];
When ItemsData is nonempty, the drop-down component
Value property stores the data associated with the selected
item.
value = dd.Value
value =
"#F00"
Since R2023a
Create a drop-down UI component with three items.
fig = uifigure; dd = uidropdown(fig,"Items",["Good","Fair","Poor"]);
Create three background color styles.
s1 = uistyle("BackgroundColor","#77AC30"); s2 = uistyle("BackgroundColor","#EDB120"); s3 = uistyle("BackgroundColor","#F77A8F");
Add the styles to the drop-down component items to change their background colors.
addStyle(dd,s1,"item",1); addStyle(dd,s2,"item",2); addStyle(dd,s3,"item",3);
The item background colors update, and the appearance of the component reflects the style of the selected item. The style does not change the color that displays when a user points to an item.
Create an app that changes the color of a plotted line when an app user makes a selection from a drop-down list.
In a file named plotOptions.m, write a function that implements the app:
Create a UI figure and a grid layout manager to lay out the app.
Create UI axes and a drop-down component in the grid layout manager.
Write a callback function named
updatePlotthat changes the plot color based on the selected drop-down component item, and assign the function to theValueChangedFcncallback property. For more information about callbacks, see Create Callbacks for Apps Created Programmatically.
function plotOptions fig = uifigure; g = uigridlayout(fig); g.RowHeight = {'1x','fit','1x'}; g.ColumnWidth = {'1x','fit'}; ax = uiaxes(g); ax.Layout.Row = [1 3]; ax.Layout.Column = 1; x = linspace(-2*pi,2*pi); y = sin(x); p = plot(ax,x,y,"Color","#F00"); dd = uidropdown(g, ... "Items",["Red","Yellow","Blue","Green"], ... "ItemsData",["#F00" "#FF0" "#00F" "#0F0"], ... "ValueChangedFcn",@(src,event) updatePlot(src,p)); dd.Layout.Row = 2; dd.Layout.Column = 2; end function updatePlot(src,p) val = src.Value; p.Color = val; end
Run the plotOptions function. Select an item from the drop-down list to change the plot color.
plotOptions
Create an app that allows a user to choose an image to display. Because the app contains an editable drop-down component, write your code to handle users selecting an existing item and users entering their own value.
In a file named imageApp.m, write a function that implements the app:
Create a UI figure and a grid layout manager to lay out the app.
Create an editable drop-down component and an image component in the grid layout manager.
Write a callback function named
updateImagethat changes the image based on the selected drop-down component item, and assign the function to theValueChangedFcncallback property. Query the callback event data to check if the new value was selected from the existing items or was entered by the user, and validate any user-entered value. For more information about callbacks, see Create Callbacks for Apps Created Programmatically.
function imageApp fig = uifigure; g = uigridlayout(fig,[2 3]); g.RowHeight = {22,'1x'}; g.ColumnWidth = {'1x','fit','1x'}; dd = uidropdown(g, ... "Editable","on", ... "Items",["peppers.png","street1.jpg"]); dd.Layout.Row = 1; dd.Layout.Column = 2; im = uiimage(g,"ImageSource","peppers.png"); im.Layout.Row = 2; im.Layout.Column = [1 3]; dd.ValueChangedFcn = @(src,event)updateImage(src,event,im,fig); end function updateImage(src,event,im,fig) val = src.Value; if event.Edited && ~exist(val,"file") im.ImageSource = ""; uialert(fig,"Enter a file on the MATLAB path","Invalid Image") else im.ImageSource = val; end end
Run the imageApp function and update the image by selecting an existing item or by entering your own image path.
