[AddComponentMenu("UI/Legacy/Dropdown", 102)]
[RequireComponent(typeof(RectTransform))]
public class Dropdown : Selectable, IMoveHandler, IPointerDownHandler, IPointerUpHandler, IPointerEnterHandler, IPointerExitHandler, ISelectHandler, IDeselectHandler, IPointerClickHandler, ISubmitHandler, ICancelHandler, IEventSystemHandler

Constructors

Dropdown()

Declaration

protected Dropdown()

Properties

alphaFadeSpeed

The time interval at which a drop down will appear and disappear

Declaration

public float alphaFadeSpeed { get; set; }

Property Value

Type	Description
Single

captionImage

The Image component to hold the image of the currently selected option.

Declaration

public Image captionImage { get; set; }

Property Value

Type	Description
Image

captionText

The Text component to hold the text of the currently selected option.

Declaration

public Text captionText { get; set; }

Property Value

Type	Description
Text

itemImage

The Image component to hold the image of the item

Declaration

public Image itemImage { get; set; }

Property Value

Type	Description
Image

itemText

The Text component to hold the text of the item.

Declaration

public Text itemText { get; set; }

Property Value

Type	Description
Text

onValueChanged

A UnityEvent that is invoked when when a user has clicked one of the options in the dropdown list.

Declaration

public Dropdown.DropdownEvent onValueChanged { get; set; }

Property Value

Type	Description
Dropdown.DropdownEvent

Remarks

Use this to detect when a user selects one or more options in the Dropdown. Add a listener to perform an action when this UnityEvent detects a selection by the user. See https://learn.u3d.cn/topics/scripting/delegates for more information on delegates.

Examples

//Create a new Dropdown GameObject by going to the Hierarchy and clicking Create>UI>Dropdown. Attach this script to the Dropdown GameObject.
//Set your own Text in the Inspector window

using UnityEngine;
using UnityEngine.UI;

public class Example : MonoBehaviour
{
    Dropdown m_Dropdown;
    public Text m_Text;

    void Start()
    {
        //Fetch the Dropdown GameObject
        m_Dropdown = GetComponent<Dropdown>();
        //Add listener for when the value of the Dropdown changes, to take action
        m_Dropdown.onValueChanged.AddListener(delegate {
                DropdownValueChanged(m_Dropdown);
            });

        //Initialise the Text to say the first value of the Dropdown
        m_Text.text = "First Value : " + m_Dropdown.value;
    }

    //Ouput the new value of the Dropdown into Text
    void DropdownValueChanged(Dropdown change)
    {
        m_Text.text =  "New Value : " + change.value;
    }
}

options

The list of possible options. A text string and an image can be specified for each option.

Declaration

public List<Dropdown.OptionData> options { get; set; }

Property Value

Type	Description
List<Dropdown.OptionData>

Remarks

This is the list of options within the Dropdown. Each option contains Text and/or image data that you can specify using UI.Dropdown.OptionData before adding to the Dropdown list. This also unlocks the ability to edit the Dropdown, including the insertion, removal, and finding of options, as well as other useful tools

Examples

//Create a new Dropdown GameObject by going to the Hierarchy and clicking __Create__>__UI__>__Dropdown__. Attach this script to the Dropdown GameObject.

using UnityEngine;
using UnityEngine.UI;
using System.Collections.Generic;

public class Example : MonoBehaviour
{
    //Use these for adding options to the Dropdown List
    Dropdown.OptionData m_NewData, m_NewData2;
    //The list of messages for the Dropdown
    List<Dropdown.OptionData> m_Messages = new List<Dropdown.OptionData>();


    //This is the Dropdown
    Dropdown m_Dropdown;
    string m_MyString;
    int m_Index;

    void Start()
    {
        //Fetch the Dropdown GameObject the script is attached to
        m_Dropdown = GetComponent<Dropdown>();
        //Clear the old options of the Dropdown menu
        m_Dropdown.ClearOptions();

        //Create a new option for the Dropdown menu which reads "Option 1" and add to messages List
        m_NewData = new Dropdown.OptionData();
        m_NewData.text = "Option 1";
        m_Messages.Add(m_NewData);

        //Create a new option for the Dropdown menu which reads "Option 2" and add to messages List
        m_NewData2 = new Dropdown.OptionData();
        m_NewData2.text = "Option 2";
        m_Messages.Add(m_NewData2);

        //Take each entry in the message List
        foreach (Dropdown.OptionData message in m_Messages)
        {
            //Add each entry to the Dropdown
            m_Dropdown.options.Add(message);
            //Make the index equal to the total number of entries
            m_Index = m_Messages.Count - 1;
        }
    }

    //This OnGUI function is used here for a quick demonstration. See the [[wiki:UISystem|UI Section]] for more information about setting up your own UI.
    void OnGUI()
    {
        //TextField for user to type new entry to add to Dropdown
        m_MyString = GUI.TextField(new Rect(0, 40, 100, 40), m_MyString);

        //Press the "Add" Button to add a new entry to the Dropdown
        if (GUI.Button(new Rect(0, 0, 100, 40), "Add"))
        {
            //Make the index the last number of entries
            m_Index = m_Messages.Count;
            //Create a temporary option
            Dropdown.OptionData temp = new Dropdown.OptionData();
            //Make the option the data from the TextField
            temp.text = m_MyString;

            //Update the messages list with the TextField data
            m_Messages.Add(temp);

            //Add the Textfield data to the Dropdown
            m_Dropdown.options.Insert(m_Index, temp);
        }

        //Press the "Remove" button to delete the selected option
        if (GUI.Button(new Rect(110, 0, 100, 40), "Remove"))
        {
            //Remove the current selected item from the Dropdown from the messages List
            m_Messages.RemoveAt(m_Dropdown.value);
            //Remove the current selection from the Dropdown
            m_Dropdown.options.RemoveAt(m_Dropdown.value);
        }
    }
}

template

The Rect Transform of the template for the dropdown list.

Declaration

public RectTransform template { get; set; }

Property Value

Type	Description
RectTransform

value

The Value is the index number of the current selection in the Dropdown. 0 is the first option in the Dropdown, 1 is the second, and so on.

Declaration

public int value { get; set; }

Property Value

Type	Description
Int32

Examples

//Create a new Dropdown GameObject by going to the Hierarchy and clicking __Create__>__UI__>__Dropdown__. Attach this script to the Dropdown GameObject.
//Set your own Text in the Inspector window

using UnityEngine;
using UnityEngine.UI;

public class Example : MonoBehaviour
{
    //Attach this script to a Dropdown GameObject
    Dropdown m_Dropdown;
    //This is the string that stores the current selection m_Text of the Dropdown
    string m_Message;
    //This Text outputs the current selection to the screen
    public Text m_Text;
    //This is the index value of the Dropdown
    int m_DropdownValue;

    void Start()
    {
        //Fetch the DropDown component from the GameObject
        m_Dropdown = GetComponent<Dropdown>();
        //Output the first Dropdown index value
        Debug.Log("Starting Dropdown Value : " + m_Dropdown.value);
    }

    void Update()
    {
        //Keep the current index of the Dropdown in a variable
        m_DropdownValue = m_Dropdown.value;
        //Change the message to say the name of the current Dropdown selection using the value
        m_Message = m_Dropdown.options[m_DropdownValue].text;
        //Change the onscreen Text to reflect the current Dropdown selection
        m_Text.text = m_Message;
    }
}

Methods

AddOptions(List<String>)

Add multiple text-only options to the options of the Dropdown based on a list of strings.

Declaration

public void AddOptions(List<string> options)

Parameters

Type	Name	Description
List<String>	options	The list of text strings to add.

Remarks

Add a List of string messages to the Dropdown. The Dropdown shows each member of the list as a separate option.

Examples

//Create a new Dropdown GameObject by going to the Hierarchy and clicking Create>UI>Dropdown. Attach this script to the Dropdown GameObject.

using System.Collections.Generic;
using UnityEngine;
using UnityEngine.UI;

public class Example : MonoBehaviour
{
    //Create a List of new Dropdown options
    List<string> m_DropOptions = new List<string> { "Option 1", "Option 2"};
    //This is the Dropdown
    Dropdown m_Dropdown;

    void Start()
    {
        //Fetch the Dropdown GameObject the script is attached to
        m_Dropdown = GetComponent<Dropdown>();
        //Clear the old options of the Dropdown menu
        m_Dropdown.ClearOptions();
        //Add the options created in the List above
        m_Dropdown.AddOptions(m_DropOptions);
    }
}

AddOptions(List<Sprite>)

Add multiple image-only options to the options of the Dropdown based on a list of Sprites.

Declaration

public void AddOptions(List<Sprite> options)

Parameters

Type	Name	Description
List<Sprite>	options	The list of Sprites to add.

Remarks

See AddOptions(List<string> options) for code example of usages.

AddOptions(List<Dropdown.OptionData>)

Add multiple options to the options of the Dropdown based on a list of OptionData objects.

Declaration

public void AddOptions(List<Dropdown.OptionData> options)

Parameters

Type	Name	Description
List<Dropdown.OptionData>	options	The list of OptionData to add.

Remarks

See AddOptions(List<string> options) for code example of usages.

Awake()

Declaration

protected override void Awake()

Overrides

Selectable.Awake()

ClearOptions()

Clear the list of options in the Dropdown.

Declaration

public void ClearOptions()

CreateBlocker(Canvas)

Create a blocker that blocks clicks to other controls while the dropdown list is open.

Declaration

protected virtual GameObject CreateBlocker(Canvas rootCanvas)

Parameters

Type	Name	Description
Canvas	rootCanvas	The root canvas the dropdown is under.

Returns

Type	Description
GameObject	The created blocker object

Remarks

Override this method to implement a different way to obtain a blocker GameObject.

CreateDropdownList(GameObject)

Create the dropdown list to be shown when the dropdown is clicked. The dropdown list should correspond to the provided template GameObject, equivalent to instantiating a copy of it.

Declaration

protected virtual GameObject CreateDropdownList(GameObject template)

Parameters

Type	Name	Description
GameObject	template	The template to create the dropdown list from.

Returns

Type	Description
GameObject	The created drop down list gameobject.

Remarks

Override this method to implement a different way to obtain a dropdown list GameObject.

CreateItem(Dropdown.DropdownItem)

Create a dropdown item based upon the item template.

Declaration

protected virtual Dropdown.DropdownItem CreateItem(Dropdown.DropdownItem itemTemplate)

Parameters

Type	Name	Description
Dropdown.DropdownItem	itemTemplate	e template to create the option item from.

Returns

Type	Description
Dropdown.DropdownItem	The created dropdown item component

Remarks

Override this method to implement a different way to obtain an option item. The option item should correspond to the provided template DropdownItem and its GameObject, equivalent to instantiating a copy of it.

DestroyBlocker(GameObject)

Convenience method to explicitly destroy the previously generated blocker object

Declaration

protected virtual void DestroyBlocker(GameObject blocker)

Parameters

Type	Name	Description
GameObject	blocker	The blocker object to destroy.

Remarks

Override this method to implement a different way to dispose of a blocker GameObject that blocks clicks to other controls while the dropdown list is open.

DestroyDropdownList(GameObject)

Convenience method to explicitly destroy the previously generated dropdown list

Declaration

protected virtual void DestroyDropdownList(GameObject dropdownList)

Parameters

Type	Name	Description
GameObject	dropdownList	The dropdown list GameObject to destroy

Remarks

Override this method to implement a different way to dispose of a dropdown list GameObject.

DestroyItem(Dropdown.DropdownItem)

Convenience method to explicitly destroy the previously generated Items.

Declaration

protected virtual void DestroyItem(Dropdown.DropdownItem item)

Parameters

Type	Name	Description
Dropdown.DropdownItem	item	The Item to destroy.

Remarks

Override this method to implement a different way to dispose of an option item. Likely no action needed since destroying the dropdown list destroys all contained items as well.

Hide()

Hide the dropdown list. I.e. close it.

Declaration

public void Hide()

OnCancel(BaseEventData)

This will hide the dropdown list.

Declaration

public virtual void OnCancel(BaseEventData eventData)

Parameters

Type	Name	Description
BaseEventData	eventData	The asocciated event data.

Implements

ICancelHandler.OnCancel(BaseEventData)

Remarks

Called by a BaseInputModule when a Cancel event occurs.

OnDisable()

Declaration

protected override void OnDisable()

Overrides

Selectable.OnDisable()

OnPointerClick(PointerEventData)

Handling for when the dropdown is initially 'clicked'. Typically shows the dropdown

Declaration

public virtual void OnPointerClick(PointerEventData eventData)

Parameters

Type	Name	Description
PointerEventData	eventData	The asocciated event data.

Implements

IPointerClickHandler.OnPointerClick(PointerEventData)

OnSubmit(BaseEventData)

Handling for when the dropdown is selected and a submit event is processed. Typically shows the dropdown

Declaration

public virtual void OnSubmit(BaseEventData eventData)

Parameters

Type	Name	Description
BaseEventData	eventData	The asocciated event data.

Implements

ISubmitHandler.OnSubmit(BaseEventData)

RefreshShownValue()

Refreshes the text and image (if available) of the currently selected option.

Declaration

public void RefreshShownValue()

Remarks

If you have modified the list of options, you should call this method afterwards to ensure that the visual state of the dropdown corresponds to the updated options.

SetValueWithoutNotify(Int32)

Set index number of the current selection in the Dropdown without invoking onValueChanged callback.

Declaration

public void SetValueWithoutNotify(int input)

Parameters

Type	Name	Description
Int32	input	The new index for the current selection.

Show()

Show the dropdown.

Plan for dropdown scrolling to ensure dropdown is contained within screen.

We assume the Canvas is the screen that the dropdown must be kept inside. This is always valid for screen space canvas modes. For world space canvases we don't know how it's used, but it could be e.g. for an in-game monitor. We consider it a fair constraint that the canvas must be big enough to contain dropdowns.