Skip to main content
Version: main (4.5)

Choice Dropdown

The choicedropdown form field creates a dropdown list with multiple options. It is different from a standard select dropdown in that each option can have extra icons and descriptions. This field is often used in forms to facilitate the selection of a non-trivial option that demands additional information.

Using the choicedropdown Form Field

While most form API fields use primitive data types, the choicedropdown form field uses a particular data definition called choicelist. This data definition is an abstraction that represents a user choice list and is used in other UI components like core\output\local\dropdown\status or core\output\local\action_menu\subpanel.

The choicelist class provides a way to define a list of options with additional information such as icons, descriptions, the currently selected option, or the ability to disable specific options.

Example Usage

To create a choicedropdown form field, you need to:

  1. Create a new instance of the choicelist class.
  2. Add options and any extra information to the choicelist instance.
  3. Add the choicedropdown form field to the form, passing the choicelist instance.
// Define the options for the dropdown list.
$options = new core\output\choicelist();
"Text option 1",
'description' => 'Option 1 description',
'icon' => new pix_icon('t/hide', 'Eye icon 1'),
"Text option 2",
'description' => 'Option 2 description',
'icon' => new pix_icon('t/stealth', 'Eye icon 2'),
"Text option 3",
'description' => 'Option 3 description',
'icon' => new pix_icon('t/show', 'Eye icon 3'),

// Add the choicedropdown field to the form.
get_string('FIELDNAME', 'PLUGINNAME'),
$mform->setDefault('FIELDNAME', $defaultvalue);