Dropdown

Description

The dropdown field type creates a select menu in the admin panel, allowing users to choose one option from a predefined list. It is rendered as an HTML <select> element styled with Bootstrap’s form-select class. This field is ideal for scenarios where users need to select a single value from a controlled set of options, such as categories, statuses, or preferences.

Available Options

Parameter Type Description Required Default
name String The name of the field, used as the identifier and default label if label is not provided. Yes –
type String The field type. Must be set to dropdown. Yes –
label String The display label for the dropdown field. If not provided, the name is used. No name
options Array An array of strings representing the available options in the dropdown. Each option is displayed and stored as its string value. Yes –
default String/Boolean The default selected option. Must match one of the options values if provided. If set to false, no option is selected by default. No false
disabled Boolean If true, the dropdown is disabled, preventing user interaction. No false
class String Additional CSS classes to apply to the dropdown for custom styling or JavaScript targeting. No –
help String A help message displayed in a sidebar or tooltip when the user clicks the info icon next to the field. No –
required Boolean If true, the field is marked as required, adding the HTML required attribute. No false


Note: The dropdown field is stored in the settings array as a sanitized string, using WordPress’s sanitize_text_field function. The stored value corresponds to the selected option’s string value.

Example

Below is an example of how to define a dropdown field in the $fields array for the Reusable Admin Panel settings class.

$this->fields = array(
    'general' => array(
        array(
            'name'    => __('Color', 'your-plugin-slug'),
            'type'    => 'dropdown',
            'label'   => __('Select Color', 'your-plugin-slug'),
            'options' => array('Red', 'Blue', 'Green'),
            'default' => 'Blue',
            'class'   => 'color-selector',
            'help'    => __('Choose a color from the list.', 'your-plugin-slug'),
            'required' => true
        )
    )
);

This configuration will create a dropdown field labeled “Select Color” under the “general” section. It will offer three options (Red, Blue, Green), default to Blue, include the CSS class color-selector, display a help message, and be marked as required.

Usage Notes

  • The dropdown field uses WordPress’s sanitize_text_field for sanitization, ensuring the selected option is a safe string.
  • The field’s ID is automatically generated as {section}-{name}, where name is sanitized using sanitize_title.
  • The field is styled using Bootstrap’s form-select class. Custom styles can be applied via the class parameter.
  • A placeholder option (Select Option) is included by default, which is disabled and selected if no default is set. This option has an empty value and does not persist upon saving.
  • The required attribute ensures a valid option is selected, triggering browser validation.
  • The disabled attribute, if set to true, prevents user interaction, useful for read-only displays.
  • To retrieve the value of a dropdown field, use the get_option method, e.g., $this->get_option('general', 'color').