Viewi

Viewi UI

Dropdown Menu

DropdownMenu is a small button that opens a list of actions. Use it for the actions of a row, a card or a file. You give it a list of DropdownMenuItem objects, and it emits select with the key of the item the user picks. Your component decides what that key means.

Usage

Chosen: nothing yet 
<DropdownMenu items="$items" label="File actions" (select)="onAction" />
<span class="text-muted">Chosen: {$chosen === '' ? 'nothing yet' : $chosen}</span>
<?php

use Viewi\Components\BaseComponent;
use Viewi\UI\Components\Dropdown\DropdownMenuItem;

class FilesPage extends BaseComponent
{
    public array $items = [];
    public string $chosen = '';

    public function mounted()
    {
        $this->items = [
            new DropdownMenuItem('rename', 'Rename', 'bi-pencil'),
            new DropdownMenuItem('copy', 'Duplicate', 'bi-files'),
            // disabled
            new DropdownMenuItem('archive', 'Archive', 'bi-archive', false, true),
            // danger
            new DropdownMenuItem('delete', 'Delete', 'bi-trash', true),
        ];
    }

    public function onAction(string $key)
    {
        $this->chosen = $key;
    }
}

A disabled item is shown but you can not choose it, and the keyboard skips it. A danger item is shown in the danger color, so the user notices a destructive action before clicking it.

Button with text

By default the trigger shows only the bi-three-dots icon. Set text to show a label next to the icon, icon to change the icon, and buttonClass to change the look of the button.

Chosen: nothing yet 
<DropdownMenu items="$moveItems" label="Move file" icon="bi-folder-symlink" text="Move to..."
    buttonClass="btn btn-sm btn-outline-secondary" align="start" (select)="onAction" />

Set icon="" if you want text only.

Menus in a list

The trigger stops its click from bubbling up. This means a menu inside a clickable row does not also trigger the row click. Put the menu next to the row button, not inside it: a button inside another button is not valid HTML.

Only one menu is open at a time on the page. Opening a menu closes the one that was open before.

Opened: nothing yet
Chosen: nothing yet
<div class="list-group">
    <div foreach="$files as $file" class="list-group-item d-flex align-items-center p-1">
        <button type="button" class="btn btn-sm flex-grow-1 text-start" (click)="openFile($file)">{$file}</button>
        <DropdownMenu items="$items" label="{'Actions for ' . $file}" (select)="onAction" />
    </div>
</div>

Position

The menu is rendered at the end of the body element, so a scrolling panel or a table cell does not cut it off. It opens below the trigger. With align="end" (the default) its right edge lines up with the right edge of the trigger, and the menu opens to the left. With align="start" its left edge lines up with the left edge of the trigger. If the menu does not fit in the window, it is moved back inside.

Keyboard

  • On the trigger: Enter, Space or ArrowDown opens the menu on the first item, ArrowUp opens it on the last item.
  • In the menu: ArrowUp and ArrowDown move between items (wrapping around and skipping disabled items), Home and End jump to the first and last item, Enter or Space chooses the item.
  • Escape closes the menu and moves focus back to the trigger. Tab closes the menu.
  • A click outside the menu closes it.

Properties

DropdownMenu

items - list of DropdownMenuItem objects to show. Default: [].

label - (optional) accessible name of the trigger and the menu, also used as the trigger's tooltip. Describe what the actions are for. Default: Actions.

icon - (optional) icon of the trigger. Set it to an empty string to hide the icon. Default: bi-three-dots.

text - (optional) text shown next to the icon. Default: `` (empty), icon only.

buttonClass - (optional) class list of the trigger button. Default: btn btn-sm btn-link dropdown-menu-trigger.

align - (optional) horizontal alignment of the menu to the trigger: end or start. Default: end.

DropdownMenuItem

DropdownMenuItem is a data class. Create it with new DropdownMenuItem($key, $label, $icon, $danger, $disabled).

key - the string emitted with select when the item is chosen.

label - the text of the item.

icon - (optional) icon shown before the label. Default: `` (empty), no icon.

danger - (optional) shows the item in the danger color. Use it for destructive actions like delete. Default: false.

disabled - (optional) the item is shown but can not be chosen. Default: false.

Events

DropdownMenu

(select) - happens when the user chooses an item. The event value is the item's key. The menu closes and focus returns to the trigger.