MenuListbox
A MenuListbox is a standalone, always-visible list container that supports single-select and multi-select modes. It supports grouping with category headers, dividers, icons, helper text, and descriptions.
Import
- React
- Angular
- Vue.js
// with @dhl-official/react-library:
import { DhlMenuListbox } from "@dhl-official/react-library"
// with @dhl-official/ui-libraries/react-library:
import { DhlMenuListbox } from "@dhl-official/ui-libraries/react-library"
If the DUIL has been installed, you can use the web component directly:
<duil321-dhl-menu-listbox></duil321-dhl-menu-listbox>
If the DUIL has been installed, you can use the web component directly:
<duil321-dhl-menu-listbox></duil321-dhl-menu-listbox>
Code
- React
- Angular
- Vue.js
<DhlMenuListbox
data={[
{ label: "Urgent", value: "urgent" },
{ label: "High", value: "high" },
{ label: "Medium", value: "medium" },
{ label: "Low", value: "low" },
]}
dataAriaLabel="Priority"
onDhlChange={(e) => console.log(e.detail.value)}
/>
<duil321-dhl-menu-listbox
[data]="items"
data-aria-label="Priority"
(dhlChange)="onSelect($event)"
></duil321-dhl-menu-listbox>
<duil321-dhl-menu-listbox
:data="items"
data-aria-label="Priority"
@dhl-change="onSelect"
></duil321-dhl-menu-listbox>
Interactive Demo
Readme
Usage
Dhl-menu-listbox
Snippets of code in HTML and JavaScript to show some of the use cases for the component. The code is not meant to be executed, but to be used as a reference for the usage of the component. Angular, React and Vue usages are not included in this documentation, but can be easily derived from the html and javascript code.
default usage
duil321-dhl-menu-listbox is data-driven: pass an array of items through the data
prop. It is not a popover itself - it's the listbox surface a consumer
positions and shows/hides (see duil321-dhl-dropdown or duil321-dhl-table for examples of
wiring it up behind a trigger).
<duil321-dhl-menu-listbox id="listbox" data-aria-label="Choose a service"></duil321-dhl-menu-listbox>
<script type="module">
const listbox = document.querySelector("#listbox");
listbox.data = [
{ label: "Express", value: "express" },
{ label: "Standard", value: "standard" },
{ label: "Economy", value: "economy" },
];
listbox.addEventListener("dhlChange", (e) => {
console.log(e.detail.value, e.detail.values);
});
</script>
multi-select usage
Set multiSelect to allow more than one item to be selected at once. The
dhlChange event detail always includes both value (the first selected
item) and values (the full selection).
<duil321-dhl-menu-listbox id="multi-listbox" multi-select></duil321-dhl-menu-listbox>
<script type="module">
const listbox = document.querySelector("#multi-listbox");
listbox.data = [
{ label: "Express", value: "express" },
{ label: "Standard", value: "standard" },
{ label: "Economy", value: "economy" },
];
</script>
usage with a built-in filter
Set filter to render an embedded search input above the items, for cases
where the listbox is used standalone or triggered from a component that
doesn't already provide its own search input (e.g. a button-triggered popover
menu). Use filterPlaceholder to customise its placeholder text.
duil321-dhl-menu-listbox does not filter data itself: listen for dhlFilterInput
and pass a filtered data array back in. Typing "Open" in the example below
would call listbox.data = filtered.
<duil321-dhl-menu-listbox id="filterable-listbox" filter filter-placeholder="Search actions"></duil321-dhl-menu-listbox>
<script type="module">
const listbox = document.querySelector("#filterable-listbox");
const allItems = [
{ label: "Open", value: "open" },
{ label: "Save", value: "save" },
{ label: "Save as...", value: "save-as" },
{ label: "Close", value: "close" },
];
listbox.data = allItems;
listbox.addEventListener("dhlFilterInput", (e) => {
const query = e.detail.toLowerCase();
listbox.data = allItems.filter((item) =>
item.label.toLowerCase().includes(query),
);
});
</script>
Keyboard behavior when filter is enabled:
- Tab moves focus into the filter input first.
- Arrow Down from the filter input moves focus to the first visible item.
- Arrow Up from the first item returns focus to the filter input.
- Escape in the filter input clears its value and emits
dhlFilterInputwith an empty string.
usage with the default slot instead of a selection item
Most items come from the data array, but a type: "slot" entry reserves a
position in the list for arbitrary markup instead of a duil321-dhl-selection-option
row - for example a "Create new..." action or a custom footer link. Any light
DOM children of duil321-dhl-menu-listbox are rendered into that reserved position,
wherever the { type: "slot" } entry sits in data. Only one type: "slot"
entry is supported per listbox.
<duil321-dhl-menu-listbox id="listbox-with-slot">
<duil321-dhl-button variant="text">+ Create new label</duil321-dhl-button>
</duil321-dhl-menu-listbox>
<script type="module">
const listbox = document.querySelector("#listbox-with-slot");
listbox.data = [
{ label: "Shipping", value: "shipping" },
{ label: "Billing", value: "billing" },
{ type: "slot" },
];
</script>
Keyboard and selection behavior:
- The slot position is skipped by
ArrowUp/ArrowDown/Home/Endnavigation between items, the same waydividerandcategoryentries are - it never becomes theactiveIndex. - It does not participate in
dhlChange: clicking/activating it is entirely up to the markup you slot in (e.g. aduil321-dhl-button's own click handler).
configuring a slot row properly
The .slot-item wrapper only contributes the outer padding shared with the
rest of the list (--duil321-dui-size-space-2x vertically, --duil321-dui-size-space-8x
horizontally) - everything inside it is plain light DOM markup, so a few
rules keep a custom row behaving and looking like a real list item:
- Width and alignment - content doesn't automatically span the row, and
isFullWidthon aduil321-dhl-buttonis not the same as a left-aligned row:duil321-dhl-buttonalways centers its own label (justify-content/text-align: centerare baked into its CSS, regardless of width), so a full-width button reads as centered text, not a left-aligned list item. Wrap the content in aduil321-dhl-flexrow instead -width="var(--duil321-dui-size-space-full)"(the default) to span the row andjustify="flex-start"to keep natural- width content (a button, a label + control, etc.) pinned to the left edge like every other row in the list. - Spacing between multiple rows - when slotting more than one row (see
the fully-slotted examples below), stack them with
duil321-dhl-vstack gap="var(--duil321-dui-size-space-2x)"and give each row its ownduil321-dhl-flex padding="var(--duil321-dui-size-space-2x) var(--duil321-dui-size-space-4x)", which keeps the vertical rhythm close to regular items. - Flex direction inheritance -
duil321-dhl-vstackis itself aduil321-dhl-flex direction="column"under the hood, and--directionis a CSS custom property, so it inherits into anyduil321-dhl-flexnested inside it. Always setdirection="row"explicitly on a row's ownduil321-dhl-flex, or it silently inheritscolumnfrom the surroundingduil321-dhl-vstackandjustify/alignend up acting on the vertical axis instead of the horizontal one - content that should sit side by side stacks instead. - Focusability - since the slot position is entirely skipped by the
roving-tabindex/arrow-key logic above, every interactive element you slot
in must be natively focusable on its own (a real
<button>,duil321-dhl-button,duil321-dhl-switch, a link, etc.) - a plain<div>with a click handler is not reachable by keyboard. - Labeling - prefer a control's own native label prop (
labelonduil321-dhl-switch,variant.labelonduil321-dhl-input-field) over pairing it with a separate<span>: it's one less element, and it sidesteps the direction pitfall above entirely since there's only ever one child in the row. Only fall back todataAriaLabelfor controls that have no visible-label prop at all, likeduil321-dhl-toggle-control. - Hover/selected styling -
duil321-dhl-selection-optionrows tint their background on hover and keyboard focus automatically; slotted rows do not get that treatment. If you want a highlighted-row look, add it to your own markup - it isn't applied to.slot-itemfor you.
slot item pinned to the top of the list
The slot's position is wherever you put the { type: "slot" } entry in
data - put it first to pin an action above the regular items instead of
below them.
<duil321-dhl-menu-listbox id="listbox-with-top-slot">
<duil321-dhl-button variant="text">+ Create new label</duil321-dhl-button>
</duil321-dhl-menu-listbox>
<script type="module">
const listbox = document.querySelector("#listbox-with-top-slot");
listbox.data = [
{ type: "slot" },
{ label: "Shipping", value: "shipping" },
{ label: "Billing", value: "billing" },
];
</script>
slot item separated by a divider
Pair the slot entry with a divider entry to visually detach a footer action
from the rest of the list, a common pattern for "Create new..." or "Manage
labels..." links.
<duil321-dhl-menu-listbox id="listbox-with-divided-slot">
<duil321-dhl-button variant="text">+ Create new label</duil321-dhl-button>
</duil321-dhl-menu-listbox>
<script type="module">
const listbox = document.querySelector("#listbox-with-divided-slot");
listbox.data = [
{ label: "Shipping", value: "shipping" },
{ label: "Billing", value: "billing" },
{ type: "divider" },
{ type: "slot" },
];
</script>
slot item combined with the built-in filter
filter and the slot position are independent - a slotted footer action is
unaffected by it unless you choose to hide it yourself. The example below
keeps a "+ Create new label" action pinned below the results regardless of
the current filter value.
<duil321-dhl-menu-listbox id="filterable-listbox-with-slot" filter>
<duil321-dhl-button variant="text">+ Create new label</duil321-dhl-button>
</duil321-dhl-menu-listbox>
<script type="module">
const listbox = document.querySelector("#filterable-listbox-with-slot");
const allItems = [
{ label: "Shipping", value: "shipping" },
{ label: "Billing", value: "billing" },
{ label: "Customs", value: "customs" },
];
const render = (items) =>
(listbox.data = [...items, { type: "slot" }]);
render(allItems);
listbox.addEventListener("dhlFilterInput", (e) => {
const query = e.detail.toLowerCase();
render(allItems.filter((item) => item.label.toLowerCase().includes(query)));
});
</script>
usage with slots only (no selection-option rows at all)
data isn't required to contain any regular items - a single
{ type: "slot" } entry still reserves exactly one position, but every light
DOM child you put inside duil321-dhl-menu-listbox renders into that one position.
Stack your own rows with duil321-dhl-vstack, and wrap each row's content in a
duil321-dhl-flex justify="flex-start" so it reads as a proper left-aligned list
rather than inline or centered content (see "Width and alignment" above -
duil321-dhl-button's own label is always centered, so plain isFullWidth is not
enough here).
duil321-dhl-vstack renders its own internal duil321-dhl-flex direction="column", and
--direction is a CSS custom property, which inherits down into nested
elements - so each row's own duil321-dhl-flex must set direction="row" itself,
or it silently inherits column from the surrounding duil321-dhl-vstack and its
justify/align end up acting on the wrong axis.
<duil321-dhl-menu-listbox id="fully-slotted-listbox" data-aria-label="Bulk actions">
<duil321-dhl-vstack gap="var(--duil321-dui-size-space-2x)">
<duil321-dhl-flex direction="row" justify="flex-start" padding="var(--duil321-dui-size-space-2x) var(--duil321-dui-size-space-4x)">
<duil321-dhl-button variant="text">Export as CSV</duil321-dhl-button>
</duil321-dhl-flex>
<duil321-dhl-flex direction="row" justify="flex-start" padding="var(--duil321-dui-size-space-2x) var(--duil321-dui-size-space-4x)">
<duil321-dhl-button variant="text">Export as PDF</duil321-dhl-button>
</duil321-dhl-flex>
<duil321-dhl-flex direction="row" justify="flex-start" padding="var(--duil321-dui-size-space-2x) var(--duil321-dui-size-space-4x)">
<duil321-dhl-button variant="text">Delete selected</duil321-dhl-button>
</duil321-dhl-flex>
</duil321-dhl-vstack>
</duil321-dhl-menu-listbox>
<script type="module">
const listbox = document.querySelector("#fully-slotted-listbox");
listbox.data = `[{ type: "slot" }]`;
</script>
This opts out of the component's built-in behavior entirely, on top of the
rules above: with no regular items, there's nothing for ArrowUp/
ArrowDown/Home/End to move between, and value/multiSelect have
nothing to act on. duil321-dhl-menu-listbox is reduced to layout and the
surrounding list chrome (border, shadow, scrolling, and the optional
filter input) - every row manages its own focus and click handling.
A list item isn't limited to a single element either - compose each row out
of more than one component, and mix different form controls row to row as
the content calls for it. The example below builds a settings menu with
three different DHL form components, one per row: a duil321-dhl-switch, a
duil321-dhl-input-field, and a duil321-dhl-checkbox. Each one sets its label through its
own native prop (label on duil321-dhl-switch and duil321-dhl-checkbox, variant.label
on duil321-dhl-input-field) rather than through an extra sibling element - a
separate <span> next to the control doesn't just duplicate markup for no
reason, it also silently breaks under the duil321-dhl-flex/duil321-dhl-vstack
direction-inheritance issue above, since now there's more than one child
fighting over the wrong axis. The input field is also given
style="width: var(--duil321-dui-size-space-full)" directly, since there's no
dedicated full-width prop on duil321-dhl-input-field the way there is on
duil321-dhl-button - its host element doesn't stretch to fill the row on its own.
<duil321-dhl-menu-listbox id="fully-slotted-mixed-listbox" data-aria-label="Preferences">
<duil321-dhl-vstack gap="var(--duil321-dui-size-space-2x)">
<duil321-dhl-flex direction="row" padding="var(--duil321-dui-size-space-2x) var(--duil321-dui-size-space-4x)">
<duil321-dhl-switch value="email" label="Email notifications" checked></duil321-dhl-switch>
</duil321-dhl-flex>
<duil321-dhl-flex direction="row" padding="var(--duil321-dui-size-space-2x) var(--duil321-dui-size-space-4x)">
<duil321-dhl-input-field
size="sm"
style="width: var(--duil321-dui-size-space-full)"
variant='{"label":"Display name","placeholder":"e.g. Priority shipments"}'
></duil321-dhl-input-field>
</duil321-dhl-flex>
<duil321-dhl-flex direction="row" padding="var(--duil321-dui-size-space-2x) var(--duil321-dui-size-space-4x)">
<duil321-dhl-checkbox value="remember-device" label="Remember this device"></duil321-dhl-checkbox>
</duil321-dhl-flex>
</duil321-dhl-vstack>
</duil321-dhl-menu-listbox>
<script type="module">
const listbox = document.querySelector("#fully-slotted-mixed-listbox");
listbox.data = `[{ type: "slot" }]`;
</script>
usage with dividers and categories
<duil321-dhl-menu-listbox id="grouped-listbox"></duil321-dhl-menu-listbox>
<script type="module">
const listbox = document.querySelector("#grouped-listbox");
listbox.data = [
{ label: "Recent", type: "category" },
{ label: "Express", value: "express" },
{ type: "divider" },
{ label: "All services", type: "category" },
{ label: "Standard", value: "standard" },
{ label: "Economy", value: "economy" },
];
</script>
Properties
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
data | data | An optional array of items to display in the listbox. | DhlMenuListboxItemType[] | [] |
dataAriaLabel | data-aria-label | An optional aria-label for the listbox, used when there is no visible label element. | string | undefined |
dataAriaLabelledby | data-aria-labelledby | An optional aria-labelledby value referencing the id of an external label element. | string | undefined |
dataId | id | An optional unique HTML id for the component. Used to link external labels via aria-labelledby. | string | `duil321-dhl-menu-listbox-${getRandomString()}` |
dataTestid | data-testid | An optional data-testid attribute for testing. | string | undefined |
filter | filter | An optional flag to render an embedded filter/search input at the top of the listbox, above the items. Useful when the listbox is used standalone or triggered from a component that doesn't provide its own search input. When false (default) the listbox renders identically to a plain listbox, with no extra wrappers or spacing. | boolean | false |
filterPlaceholder | filter-placeholder | An optional placeholder for the filter input, shown when filter is true. | string | "Search…" |
multiSelect | multi-select | An optional flag to enable multi-select mode. When false (default) only one item can be selected at a time. | boolean | false |
notFoundLabel | not-found-label | An optional label shown in the empty / no-results state. | string | "Item not found" |
value | value | An optional selected value for single-select mode. Setting this prop initialises the selection. | string | undefined |
values | values | An optional array of selected values for multi-select mode. | string[] | [] |
Events
| Event | Description | Type |
|---|---|---|
dhlChange | Event emitted when the selection changes. The detail always includes both value (first selected string) and values (full selection array). | CustomEvent<{ value: string; values: string[]; }> |
dhlFilterInput | Emitted on each keystroke in the filter input with its current value. The consumer is responsible for filtering the data array passed back into this component. | CustomEvent<string> |
Dependencies
Used by
Depends on
- duil321-dhl-selection-option
- duil321-dhl-input-field
- duil321-dhl-text-sr-only
Graph
Built by DHL User Interface Library Team!