Skip to content
Bladewell

<x-widget.dropdown>

Dropdown Blade component for Laravel and Livewire

Menu button on the native popover: row actions, account menus, "More" buttons. Items are links, buttons, or forms that submit with any method (a delete comes with its CSRF token), and confirm="…" asks with modal.confirm() first. Arrow keys, Home/End and type-to-jump, flips above when there's no room, and never clipped by a table or a modal. Works inside Livewire components: items take wire:click, confirm included.

php artisan bladewell:add dropdown
Also adds
Button, Icon, Modal
Used by
Kanban, Table
Works with
Laravel 12 and 13, Livewire 3 and 4, Tailwind CSS 4.1+, PHP 8.3+

Usage

In scripts

window.dropdown is available once the dropdown script has loaded. <x-widget.dropdown id="order-1042-actions" label="Actions for order #1042">…</x-widget.dropdown>

JavaScript
dropdown.open('order-1042-actions');
dropdown.close('order-1042-actions');
dropdown.toggle('order-1042-actions');

// Or the trigger element. A shared menu (x-widget.dropdown.menu) opens for a row, so give that row's trigger.
dropdown.open(document.querySelector('[data-order="1042"] [data-dropdown-trigger]'));

In a table

In a table, give each row's trigger a label that names the row, so a screen reader's list of buttons isn't twenty "Actions". Hiding an item with @can is only for looks: the controller must still authorize the request itself. In a long table, render the menu once instead and give each row only its trigger: see the shared menu example, where only-if takes the place of @can.

Blade
@foreach ($orders as $order)
    <tr>
        <td>#{{ $order->number }}</td>
        <td>{{ $order->customer }}</td>
        <td class="text-end">
            <x-widget.dropdown :label="'Actions for order #'.$order->number" align="end">
                <x-widget.dropdown.item :href="route('orders.edit', $order)" icon="pencil">Edit</x-widget.dropdown.item>
                @can('delete', $order)
                    <x-widget.dropdown.divider />
                    <x-widget.dropdown.item :action="route('orders.destroy', $order)" method="delete" icon="trash" danger :confirm="'Delete order #'.$order->number.'?'">Delete</x-widget.dropdown.item>
                @endcan
            </x-widget.dropdown>
        </td>
    </tr>
@endforeach

Livewire

Inside a Livewire component, an item takes wire:click like any button. confirm="…" asks first and only then runs the action, and a disabled item never runs it. A render while the menu is open leaves it open and in place, with its items updated. Choosing an item closes the menu and puts focus back on the trigger. A shared dropdown.menu fills its :name placeholders into links, form actions and data-*, never into wire:click, so keep a menu per row, as here, for items that call the component.

Blade
@foreach ($orders as $order)
    <div wire:key="order-{{ $order->id }}" class="flex items-center justify-between">
        <span>#{{ $order->number }}</span>
        <x-widget.dropdown :label="'Actions for order #'.$order->number" align="end">
            <x-widget.dropdown.item icon="copy" wire:click="duplicate({{ $order->id }})">Duplicate</x-widget.dropdown.item>
            <x-widget.dropdown.item icon="lock" wire:click="lock({{ $order->id }})" :disabled="$order->locked">Lock</x-widget.dropdown.item>
            <x-widget.dropdown.divider />
            <x-widget.dropdown.item icon="trash" danger wire:click="delete({{ $order->id }})" :confirm="'Delete order #'.$order->number.'?'">Delete</x-widget.dropdown.item>
        </x-widget.dropdown>
    </div>
@endforeach

Examples

Row actions

Actions for one record. With no trigger it's an icon-only button, so it needs a label naming the record. Edit is a link, Copy is a plain button for your own script (beside this), and Delete is a form that sends DELETE with its CSRF token once confirm has been answered. Uses orders.edit and orders.destroy routes from your app.

Order #1042

Ana Silva · $129.00

Show code
Blade
<div class="border-line flex max-w-md items-center justify-between gap-4 rounded-2xl border p-4">
    <div>
        <p class="font-medium">Order #1042</p>
        <p class="text-foreground/70 text-sm">Ana Silva · $129.00</p>
    </div>
    <x-widget.dropdown label="Actions for order #1042" align="end">
        <x-widget.dropdown.item :href="route('orders.edit', 1042)" icon="pencil">Edit</x-widget.dropdown.item>
        <x-widget.dropdown.item icon="copy" data-clipboard="1042">Copy order number</x-widget.dropdown.item>
        <x-widget.dropdown.divider />
        <x-widget.dropdown.item :action="route('orders.destroy', 1042)" method="delete" icon="trash" danger confirm="Delete order #1042?" confirm-message="The order and its invoice are removed for good.">Delete</x-widget.dropdown.item>
    </x-widget.dropdown>
</div>
JavaScript, in your own JS file
// The menu closes itself after a choice; the copy is yours.
document.addEventListener('click', (event) => {
    const item = event.target.closest('[data-clipboard]');
    if (item) {
        navigator.clipboard?.writeText(item.dataset.clipboard);
    }
});

Shared menu

For the same menu in every row of a long list or table: render it once as dropdown.menu, and in each row only its trigger, with menu="…" and that row's values. As the menu opens, its :name placeholders (in links, form actions, confirm questions, data-* and text) take the row's values, so route('orders.edit', ':id') becomes that order's link. only-if hides an item for rows where that value is false; it only hides it, so the controller must still authorize. Uses orders.edit and orders.destroy routes from your app.

Pass $orders from your controller.

  • Order #1042

    Ana Silva · $129.00

  • Order #1043

    Ben Okafor · $48.50

  • Order #1044

    Chen Wei · $310.00

Show code
Blade
<ul class="border-line divide-line max-w-md divide-y rounded-2xl border">
    @foreach ($orders as $order)
        <li class="flex items-center justify-between gap-4 p-4">
            <div>
                <p class="font-medium">Order #{{ $order['number'] }}</p>
                <p class="text-foreground/70 text-sm">{{ $order['customer'] }} · {{ $order['total'] }}</p>
            </div>
            <x-widget.dropdown menu="order-actions" :label="'Actions for order #'.$order['number']" :values="['id' => $order['id'], 'number' => $order['number'], 'can_delete' => $order['can_delete']]" />
        </li>
    @endforeach
</ul>

<x-widget.dropdown.menu id="order-actions" align="end">
    <x-widget.dropdown.item :href="route('orders.edit', ':id')" icon="pencil">Edit order #:number</x-widget.dropdown.item>
    <x-widget.dropdown.divider only-if="can_delete" />
    <x-widget.dropdown.item :action="route('orders.destroy', ':id')" method="delete" icon="trash" danger only-if="can_delete" confirm="Delete order #:number?" confirm-message="The order and its invoice are removed for good.">Delete</x-widget.dropdown.item>
</x-widget.dropdown.menu>

Account menu

The trigger slot takes your own markup, such as an avatar and a name. Other content can sit between the items, like who is signed in, but screen readers only move between items inside a menu, so say it in the trigger's label too. Sign out is a POST form. Uses profile.edit and logout routes from your app.

Show code
Blade
<x-widget.dropdown align="end" label="Account: Ana Silva, [email protected]">
    <x-slot:trigger class="hover:bg-field py-1.5 ps-1.5 pe-3">
        <span aria-hidden="true" class="bg-primary/10 text-primary grid size-8 place-items-center rounded-full text-xs font-semibold">AS</span>
        <span class="text-sm font-medium">Ana Silva</span>
        <x-widget.icon name="chevron-down" class="size-4 opacity-60" />
    </x-slot:trigger>

    <div aria-hidden="true" class="px-3 pt-1.5 pb-2">
        <p class="text-foreground/70 text-xs">Signed in as</p>
        <p class="truncate font-medium">[email protected]</p>
    </div>
    <x-widget.dropdown.divider />
    <x-widget.dropdown.item :href="route('profile.edit')" icon="user">Profile</x-widget.dropdown.item>
    <x-widget.dropdown.item :action="route('logout')" icon="log-out">Sign out</x-widget.dropdown.item>
</x-widget.dropdown>

Text trigger

A text trigger gets a chevron, and takes the button's variant and size. Here the items are links that keep the page's other query parameters. align="end" lines the menu up with the trigger's end edge; either way it flips above when there's no room below. A disabled item stays in view but can't be chosen, and the arrow keys skip it.

Show code
Blade
<div class="flex flex-wrap items-center gap-3">
    <x-widget.dropdown trigger="Export" variant="secondary">
        <x-widget.dropdown.item :href="request()->fullUrlWithQuery(['export' => 'csv'])">CSV</x-widget.dropdown.item>
        <x-widget.dropdown.item :href="request()->fullUrlWithQuery(['export' => 'xlsx'])">Excel</x-widget.dropdown.item>
        <x-widget.dropdown.item disabled>PDF (on the Pro plan)</x-widget.dropdown.item>
    </x-widget.dropdown>

    <x-widget.dropdown trigger="Sort" align="end" size="sm">
        <x-widget.dropdown.item :href="request()->fullUrlWithQuery(['sort' => 'newest'])">Newest first</x-widget.dropdown.item>
        <x-widget.dropdown.item :href="request()->fullUrlWithQuery(['sort' => 'oldest'])">Oldest first</x-widget.dropdown.item>
        <x-widget.dropdown.item :href="request()->fullUrlWithQuery(['sort' => 'amount'])">Largest amount</x-widget.dropdown.item>
    </x-widget.dropdown>
</div>

Props

Other attributes, such as autocomplete or data-*, are passed through to the element. class styles the component's outer wrapper.

<x-widget.dropdown>

Prop Default Description
id null The trigger button's id; scripts can open the menu by it, so it must be unique. Made up when left out.
trigger null Text for a button with a chevron, or an <x-slot:trigger> with your own markup (an avatar and name, say). Without it, the trigger is an icon-only button.
label null The trigger's name for screen readers. Required for the icon-only trigger; the slot trigger uses it too.
icon 'ellipsis' The icon-only trigger's icon.
variant 'neutral' The trigger's look, as on the button: primary, secondary, tertiary, danger, neutral or link.
size 'md' The trigger's size: sm, md or lg.
align 'start' Which edge of the trigger the menu lines up with: start (left in left-to-right pages) or end.
menu null The id of a shared menu (x-widget.dropdown.menu) rendered once elsewhere on the page. This dropdown is then only its trigger and opens that menu, so a long table carries one copy of its row menu instead of one per row.
values [] With menu: this row's values, filled into the menu's :name placeholders as it opens, e.g. ['id' => $order->id].

<x-widget.dropdown.divider>

Prop Default Description
only-if null In a shared menu (x-widget.dropdown.menu): hidden with the items it separates, for rows where this value is false.

<x-widget.dropdown.item>

Prop Default Description
href null Makes the item a link to this URL.
action null Makes the item a form that submits to this URL, with its CSRF token. Wins over href.
method 'post' With action: the form's method, GET, POST, PUT, PATCH or DELETE, in any case.
icon null An icon before the text.
danger false Red, for destructive actions such as delete; its confirm button is red too.
disabled false Greyed out: it can't be chosen, and the arrow keys skip it.
confirm null A question, e.g. "Delete this order?": asked in a dialog first, and the item only acts once it's confirmed.
confirm-message null With confirm: more text under the question.
confirm-label null With confirm: the confirm button's text. Defaults to the item's own text.
confirm-cancel null With confirm: the cancel button's text. Defaults to "Cancel".
only-if null In a shared menu (x-widget.dropdown.menu): the name of a value that shows the item only for rows where it is true, such as 'can_delete'. It only hides the item: the controller must still authorize the request itself.

<x-widget.dropdown.menu>

Prop Default Description
id null Unique on the page: each row's dropdown opens the menu by it, as its menu="…".
align 'start' Which edge of the trigger that opened it the menu lines up with: start (left in left-to-right pages) or end.

Accessibility

All 4 examples above are checked with axe-core against the WCAG 2.2 A and AA rules, in the light theme and the dark one, both as the page draws and with each popover, dialog, toast and tooltip opened, on every change. A change that fails can't be merged. Where axe can't decide, such as contrast on SVG text, the test measures the colours itself instead of letting it pass.

Automated checks can't judge everything: how it sounds in a screen reader, and how it feels to use from the keyboard, still need a person. Check those on your own pages too.

Source

What bladewell:add dropdown writes to your app with the default namespaces. Prefer to copy by hand? Take these files, plus the ones from the components it also adds , and the theme and base CSS.

resources/views/components/widget/dropdown/divider.blade.php Show
divider.blade.php
resources/views/components/widget/dropdown/index.blade.php Show
index.blade.php
resources/views/components/widget/dropdown/item.blade.php Show
item.blade.php
resources/views/components/widget/dropdown/menu.blade.php Show
menu.blade.php
resources/js/widget/dropdown/index.js Show
index.js
app/View/Widget/ElementIds.php Show
ElementIds.php