Dropdown

Custom select dropdown with keyboard navigation, grouped options, remote data loading, and search filtering.

Basic

Priority:

Category (custom fields):

Grouped Options

Category:

Dynamic AJAX Data

Remote Options:

// Basic dropdown
<?= $m->dropdown('priority')
    ->dataSource($priorities)
    ->value('2')
    ->placeholder('Select...')
    ->name('priority') ?>

// Custom text/value fields
<?= $m->dropdown('category', [
    'textField'  => 'name',
    'valueField' => 'id',
])->dataSource($items) ?>

// Grouped options
<?= $m->dropdown('grouped')
    ->groupedDataSource([
        ['group' => 'Work', 'items' => [
            ['value' => '1', 'text' => 'Meetings'],
        ]],
    ])
    ->placeholder('Select category...') ?>

// Remote AJAX data
<?= $m->dropdown('remote')
    ->remoteUrl('/api/options')
    ->loaderText('Loading...') ?>

// Listen for changes (addEventListener on the element)
document.getElementById('priority').addEventListener('m:dropdown:change', function(e) {
    console.log(e.detail.value, e.detail.text);
});

// Legacy callback (options.events.change) — still supported
m.dropdown('priority', {
    events: {
        change: function(data) {
            console.log(data.value, data.text);
        }
    }
});

// Get/set value
var dd = m.dropdown('priority');
dd.value();           // get
dd.value('3');        // set

// Get text
dd.text();

// Reload remote data
dd.reload();

// Enable/disable
dd.enable();
dd.disable();

// Clear selection
dd.clear();

PHP PHP Methods (Fluent)

Method / Property	Parameters	Description
`$m->dropdown($id)`	`string`	Create a dropdown component.
`->dataSource($data)`	`array`	Set local data: `[['value' => ..., 'text' => ...], ...]`.
`->textField($field)`	`string`	Property name to display (default: `"text"`).
`->valueField($field)`	`string`	Property name for the value (default: `"value"`).
`->groupedDataSource($groups)`	`array`	Grouped data: `[['group' => 'Label', 'items' => [...]]]`.
`->placeholder($text)`	`string`	Placeholder text when nothing is selected.
`->value($value)`	`?string`	Set the initially selected value.
`->name($name)`	`string`	Form field name attribute.
`->disabled()`		Disable the dropdown.
`->remoteUrl($url)`	`string`	Set the AJAX endpoint for remote data loading.
`->autoLoadRemote($auto)`	`bool`	Auto-fetch remote data on initialisation (default: `true`).
`->useLoader($use)`	`bool`	Show a loading spinner while fetching (default: `true`).
`->loaderText($text)`	`string`	Custom loading text.

JS JS Methods

Method / Property	Parameters	Description
`m.dropdown(id, options)`	`string, ?object`	Initialise or get a dropdown instance.
`value(val?)`	`?string`	Get or set the selected value.
`text()`		Get the display text of the selected item.
`dataSource(data?)`	`?array`	Get or set the flat data source array. Clears any grouped data source.
`groupedDataSource(data?)`	`?array`	Get or set the grouped data source: `[{group, items}, ...]`.
`reload()`		Re-fetch data from the remote URL. Returns a Promise.
`enable()`		Enable the dropdown.
`disable()`		Disable and close the dropdown.
`clear()`		Clear the current selection.
`configure(options)`	`object`	Update configuration at runtime.

EVENT Events

Event Name	Detail	Description
`m:dropdown:change`	`{value, text}`	Fired on the dropdown element when the selection changes. Listen with `el.addEventListener('m:dropdown:change', fn)`. The underlying `<select>` also receives a native `change` event.