{ "tag": "ed-dropdown", "kind": "component", "summary": "Dropdowns display a list of options that can be triggered by a button or other element. They support\nkeyboard navigation, submenus, and various customization options.", "status": "experimental", "level": "molecule", "since": "1.0", "docs": "https://test-apps.eurodata.de/a/eurodata-ui/docs/components/dropdown/", "usage": "https://test-apps.eurodata.de/a/eurodata-ui/docs/components/dropdown/usage/", "playwright": "getByTestId('…')", "dependencies": [ "ed-dropdown-item", "ed-popup" ], "use": [ "Grouping actions or commands behind a single trigger — edit actions, row-level actions, export options, \"more options\" overflow menus, and toolbar menus", "Actions that are used occasionally and don't each deserve a permanently visible button", "Row-level actions in a table — open, duplicate, delete — behind one More button at the end of the row", "Several export formats, such as PDF, Excel and CSV, behind a single button" ], "notFor": [ { "when": "Choosing a value that gets submitted in a form", "instead": "[Select](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/select)" }, { "when": "A searchable or type-to-filter list of many values", "instead": "[Combobox](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/combobox)" }, { "when": "Moving between pages, sections, or views", "instead": "[Tabs](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/tab-group) or a [Side Menu](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/side-menu)" }, { "when": "One frequently used action buried in a menu of rarely used variants", "instead": "a split button ([Button Group](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/button-group)), so the common action stays one click away" }, { "when": "A single, always-relevant action — except as the More menu of a [Data Grid](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/data-grid) row, which keeps its place when the row's state leaves one entry, so the action column has the same shape in every row", "instead": "a [Button](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/button)" }, { "when": "A small set of 2–4 fixed, mutually exclusive choices with short labels", "instead": "[Radio Group](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/radio-group)'s button appearance (segmented control)" } ], "rules": [ { "id": "dropdown/actions-not-values", "rule": "Use a dropdown as a menu of things to *do*, never as a control for choosing a *value*. Activating an item performs an action; it does not fill in a field, and the trigger's label never changes to reflect a \"selection\"." }, { "id": "dropdown/trigger-label", "rule": "Give the trigger a clear label that names what the menu is about — the [Button usage guide](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/button/usage) carries the full labeling rules." }, { "id": "dropdown/item-labels", "rule": "Write each item as a short action phrase, ideally starting with a verb (\"Duplicate\", \"Move to…\", \"Export as PDF\")." }, { "id": "dropdown/short-menu", "rule": "Keep the menu short — group longer menus into sections with headings and dividers so users can scan. Never pile dozens of items into one long scrolling menu.", "why": "A menu is not a place to hunt for an entry.", "check": "warning" }, { "id": "dropdown/text-label", "rule": "Give every item a visible text label and add an icon before it only when it reinforces meaning — never rely on an icon alone, and a tooltip is never a substitute.", "check": "error" }, { "id": "dropdown/shortcut-hint", "rule": "Reserve the trailing space of an item for a keyboard-shortcut hint where one exists." }, { "id": "dropdown/destructive-last", "rule": "Separate a destructive item (Delete, Reset) from the rest with a divider and place it last.", "check": "warning" }, { "id": "dropdown/checkable-items", "rule": "Use checkable items for options the user turns on and off. Don't keep the menu open for them yourself — the component does it, so several can be toggled at once.", "check": "warning" }, { "id": "dropdown/submenu-depth", "rule": "Never nest submenus more than one level deep; two levels are acceptable only as an exception when unavoidable.", "check": "error" } ], "api": { "attributes": [ { "name": "open", "property": "open", "type": "boolean", "default": "false", "description": "Opens or closes the dropdown." }, { "name": "placement", "property": "placement", "type": "'left' | 'right' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | 'top' | 'bottom' | 'right-start' | 'right-end' | 'left-start' | 'left-end'", "default": "'bottom-start'", "description": "The placement of the dropdown menu in reference to the trigger. The menu will shift to a more optimal location if\nthe preferred placement doesn't have enough room." }, { "name": "distance", "property": "distance", "type": "number", "default": "0", "description": "The distance of the dropdown menu from its trigger." }, { "name": "skidding", "property": "skidding", "type": "number", "default": "0", "description": "The offset of the dropdown menu along its trigger." }, { "name": "dir", "property": "dir", "type": "string" }, { "name": "lang", "property": "lang", "type": "string" } ], "properties": [], "methods": [ { "name": "getPropertyDescriptor", "static": true, "parameters": [ { "name": "name", "type": "PropertyKey" }, { "name": "key", "type": "string | symbol" }, { "name": "options", "type": "PropertyDeclaration" } ], "returns": "PropertyDescriptor | undefined", "description": "Wraps the accessor of reflected properties so they always hold a valid value, as a native\nreflected IDL attribute does (`button.type = undefined` reads `submit`):\n\n- A property that declares `useDefault` takes the first value set on an element for its\n default. That value is its field initializer's: the constructor has finished before markup,\n a framework or any other code can set anything. Every later `null` or `undefined` means what\n a dropped prop means on a native element — the attribute is removed: with the attribute\n there, it is removed and Lit's `useDefault` restores the default without writing it; without\n one, the property is set to the default. A value set and cleared again before the element\n updates still writes the default once, from the pending reflection.\n- A Boolean is coerced with `Boolean()`, so `undefined` is `false`.\n\nLit's `useDefault` keeps the initial default out of the DOM. Setting the default explicitly\nwrites it, as `button.type = 'submit'` writes `type`." } ], "events": [ { "name": "ed-show", "react": "onEdShow", "description": "Emitted when the dropdown is about to show. Cancelable; calling `preventDefault()` keeps it closed." }, { "name": "ed-after-show", "react": "onEdAfterShow", "description": "Emitted after the dropdown has been shown." }, { "name": "ed-hide", "react": "onEdHide", "description": "Emitted when the dropdown is about to hide. Cancelable; calling `preventDefault()` keeps it open." }, { "name": "ed-after-hide", "react": "onEdAfterHide", "description": "Emitted after the dropdown has been hidden." }, { "name": "ed-dropdown-select", "react": "onEdDropdownSelect", "type": "{ item: Element }", "description": "Emitted when an item in the dropdown is selected. Cancelable; calling `preventDefault()` leaves the selection unchanged." } ], "slots": [ { "name": "", "description": "The dropdown's items, typically `` elements." }, { "name": "trigger", "description": "The element that triggers the dropdown, such as a `` or `