{ "tag": "ed-combobox", "kind": "component", "summary": "Comboboxes combine a text input with a listbox, allowing users to filter and select from predefined options or enter custom values.", "status": "experimental", "level": "atom", "since": "1.0", "docs": "https://test-apps.eurodata.de/a/eurodata-ui/docs/components/combobox/", "usage": "https://test-apps.eurodata.de/a/eurodata-ui/docs/components/combobox/usage/", "playwright": "getByTestId('…').getByRole('combobox')", "dependencies": [ "ed-icon", "ed-option", "ed-popup", "ed-badge" ], "use": [ "A long option list (roughly 15 or more entries), where typing to filter is faster than scrolling — client names, account codes, cost centers, tax categories, employee records", "Lookups where users usually know what they want and can type part of it — search-with-suggestions, address lookup, entity search", "Adding values that don't exist in the list yet (custom entries), or building a set of tags from suggestions", "Multiple selection, when users pick several items from a large set and need to see and remove each choice", "Choosing from a hierarchy, such as a chart of accounts with account groups, where the user reasons in levels" ], "notFor": [ { "when": "A short, fixed set of choices where no filtering is needed", "instead": "[Select](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/select)" }, { "when": "2–4 fixed options with short labels", "instead": "for a single choice [Radio Group](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/radio-group) (its button appearance for compact rows), for multiple choices [Checkbox Group](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/checkbox-group)" }, { "when": "Free short text that isn't chosen from a list of suggestions", "instead": "[Input](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/input), or [Tag Input](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/tag-input) for a list of such values" }, { "when": "A yes/no or either-or toggle", "instead": "a [Switch](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/switch), [Checkbox](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/checkbox), or [Radio Group](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/radio-group)" } ], "rules": [ { "id": "combobox/select-for-short-lists", "rule": "Reach for a combobox when the list is long enough that filtering helps (roughly 15+ options). For a short, fixed set of choices use a plain [Select](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/select) or [Radio Group](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/radio-group)'s button appearance (segmented control) instead.", "why": "They are faster there — the filtering input is wasted overhead.", "check": "warning" }, { "id": "combobox/read-value-after-options", "rule": "Read `value` after the options render: a value set before its options are in the DOM reads `null` until they are — an empty array with `multiple`. With `allow-custom-value` in single mode it reads what was set." }, { "id": "combobox/tree-for-hierarchies", "rule": "Set `tree` and nest options when the choices form a hierarchy the user reasons about — folder paths, org units, nested categories, region structures. Never set it for a single level of options.", "why": "With `tree`, filtering narrows the tree in place and keeps the path to each match visible. A one-level tree is a plain list, and the chevron column only adds noise.", "check": "error" }, { "id": "combobox/no-cascade", "rule": "Don't expect selecting a parent to select its children — a parent is its own value and nothing cascades." }, { "id": "combobox/sections", "rule": "Split options with natural categories into labeled sections separated by dividers so they are easier to scan — but never rely on the small section headings alone to carry meaning.", "why": "Most assistive technology does not announce them." }, { "id": "combobox/placeholder-or-default", "rule": "Show a \"Please select…\"-style placeholder, or pre-select a sensible default, so a required field signals that a choice is expected — but never pre-select an arbitrary first option and present it as if the user chose it." }, { "id": "combobox/clear-button", "rule": "Add a clear button whenever the field can hold a value, and especially in multiple mode.", "check": "warning" }, { "id": "combobox/signal-filtering", "rule": "In a filter field, give it a placeholder like \"Type to filter…\" so it's obvious that typing narrows the list; a selection field in a form needs none." }, { "id": "combobox/explain-high-stakes", "rule": "Give critical selections (tax category, payroll account, fiscal period) extra context about what the chosen value means." }, { "id": "form-controls/visible-label", "rule": "In a form, give every control a persistent, visible label — short, descriptive and in plain language — and never placeholder text in its place. Outside a form the container decides whether the label shows; where it does not, `aria-label` gives the control its name.", "why": "Placeholder text disappears the moment the user types, leaving no reminder of what the field expected.", "check": "error" }, { "id": "form-controls/required", "rule": "Set `required` on a mandatory control and explain the required-marking convention once per form. Never add your own required indicator — the label picks it up." }, { "id": "form-controls/error-timing", "rule": "Never show a validation error before the user has interacted with the control — not on page load, not on focus alone, not while they are still typing. Don't add your own timing: the control shows its errors after the user has left it or changed its value, and on submit.", "check": "error" }, { "id": "form-controls/message-never-silenced", "rule": "Keep a message on every error. Write your own where the built-in wording does not fit — it replaces the built-in one — but never set `error` to an empty string or hide the message part: the error styling alone says that something is wrong, not what.", "check": "error" }, { "id": "form-controls/readonly-not-disabled", "rule": "Use `readonly` for a value the user can never change — a calculated total, an assigned id — and `disabled` only while it could become editable under some condition.", "why": "Disabled implies the value could be unlocked, and a disabled control submits nothing; a read-only one submits its value." }, { "id": "form-controls/min-width", "rule": "Keep a field at least 8.75rem (140px) wide, even for short values such as postal codes — and comfortably wider for prose.", "why": "The value, the label and any icons stay legible.", "check": "error", "covered": true }, { "id": "form-controls/default-density", "rule": "Keep `density` at its default, and the same for every control in one row or form. Choose `compact` or `spacious` only where the user asks for it or the space leaves no other way — a form with many fields is no reason — and then for the whole layout, never to fine-tune spacing case by case. Where a container decides the density of the controls inside it, its rules say so.", "why": "The default is the intended spacing for almost every screen.", "check": "warning" }, { "id": "form-controls/ai-suggested", "rule": "Set `ai` on a control whose value the system pre-filled, so users can tell it apart from their own entries; the state clears once they touch it." } ], "api": { "attributes": [ { "name": "name", "property": "name", "type": "null | string", "default": "''", "description": "The name of the select, submitted as a name/value pair with form data." }, { "name": "value", "property": "value", "description": "The select's value. This will be a string for single select or an array for multi-select." }, { "name": "density", "property": "density", "type": "'compact' | 'default' | 'spacious'", "default": "'default'", "description": "Controls the component's spacing density without affecting font-size." }, { "name": "placeholder", "property": "placeholder", "type": "string", "default": "''", "description": "Placeholder text to show as a hint when the select is empty." }, { "name": "multiple", "property": "multiple", "type": "boolean", "default": "false", "description": "Allows more than one option to be selected." }, { "name": "max-options-visible", "property": "maxOptionsVisible", "type": "number", "default": "3", "description": "The maximum number of selected options to show when `multiple` is true. After the maximum, \"+n\" will be shown to\nindicate the number of additional items that are selected. Set to 0 to remove the limit." }, { "name": "readonly", "property": "readonly", "type": "boolean", "default": "false", "description": "Shows a value the user cannot change. Unlike `disabled`, the control stays focusable and its value is still\nsubmitted with the form; the listbox does not open, and nothing empties the value." }, { "name": "with-clear", "property": "withClear", "type": "boolean", "default": "false", "description": "Adds a clear button when the select is not empty." }, { "name": "open", "property": "open", "type": "boolean", "default": "false", "description": "Indicates whether or not the select is open. You can toggle this attribute to show and hide the menu, or you can\nuse the `show()` and `hide()` methods and this attribute will reflect the select's open state." }, { "name": "pill", "property": "pill", "type": "boolean", "default": "false", "description": "Draws a pill-style select with rounded edges." }, { "name": "label", "property": "label", "type": "string", "default": "''", "description": "The select's label. If you need to display HTML, use the `label` slot instead." }, { "name": "aria-label", "property": "ariaLabel", "type": "null | string", "default": "null", "description": "The combobox's accessible name for when no visible label is set. Mirrored onto the internal\ndisplay input, where the combobox role lives — an aria-label left on the host alone would\nsit on a role-less element and be ignored by assistive tech. A visible label wins when both\nare present (aria-labelledby precedes aria-label in accessible-name computation)." }, { "name": "placement", "property": "placement", "type": "'top' | 'bottom'", "default": "'bottom'", "description": "The preferred placement of the select's menu. Note that the actual placement may vary as needed to keep the listbox\ninside of the viewport." }, { "name": "with-label", "property": "withLabel", "type": "boolean", "default": "false", "description": "Used for SSR purposes when a label is slotted in. Will show the label on first render." }, { "name": "with-hint", "property": "withHint", "type": "boolean", "default": "false", "description": "Used for SSR purposes when hint is slotted in. Will show the hint on first render." }, { "name": "required", "property": "required", "type": "boolean", "default": "false", "description": "The select's required attribute." }, { "name": "no-results-label", "property": "noResultsLabel", "type": "string", "default": "''", "description": "The text shown in the listbox when no option matches the current input. Defaults to a localized label.\nTo render custom markup instead, use the `no-results` slot." }, { "name": "allow-custom-value", "property": "allowCustomValue", "type": "boolean", "default": "false", "description": "When true, allows the user to enter a value that doesn't match any of the options. In single mode the typed\nvalue is committed with Enter or when the field loses focus. When `multiple` is set, Enter turns the typed\ntext into a tag (backed by a generated light-DOM option marked `data-custom-option`). When false, the\ncombobox only accepts values that match an option." }, { "name": "tree", "property": "tree", "type": "boolean", "default": "false", "description": "Renders the popup as a hierarchy instead of a flat list. Nest `` elements to any depth;\nparents expand and collapse, and every node stays selectable.\n\nNesting is only supported with this attribute set — without it there is no children slot for\nnested options to project into. Typing filters the tree in place: a parent stays visible while any\ndescendant matches.\n\nNot combinable with `allow-custom-value` (a typed string has no position in a hierarchy) or\n`autocomplete=\"none\"`; both are ignored with a warning." }, { "name": "autocomplete", "property": "autocomplete", "type": "'none' | 'list'", "default": "'list'", "description": "The autocomplete behavior of the combobox. Each value is also the `aria-autocomplete` the input\nannounces.\n- `list` (default): typing filters the listbox to options that match the entered characters;\n the typed string becomes the value unless the user selects an option.\n- `none`: the combobox is editable, but the listbox always shows all options regardless of\n the characters typed." }, { "name": "inputValue", "property": "inputValue", "type": "string", "default": "''", "description": "The current text value in the input field." }, { "name": "server", "property": "server", "type": "boolean", "default": "false", "description": "Puts the combobox in server mode without a `dataSource`: it filters nothing itself and asks for options\nthrough `ed-combobox-options-request`, answered by swapping the `` children and setting `loading`\nto false. A `dataSource` switches server mode on as well." }, { "name": "loading", "property": "loading", "type": "boolean", "default": "false", "description": "Whether options are being requested. Set as soon as a request is scheduled, the typing pause included; a\n`dataSource` clears it when its answer is in. With `server` alone, set it back to false once the options are\nswapped." }, { "name": "filter-debounce", "property": "filterDebounce", "type": "number", "default": "250", "description": "How long the typing rests before a server is asked for matching options, in milliseconds." }, { "name": "error", "property": "error", "type": "null | string", "default": "null", "description": "Draws an error-style input with danger colored border and icon. Set to an empty string (or use the bare attribute ``) to render error styling without a visible message; submission is still blocked with a localized fallback validation message. Set to a non-empty string to additionally display that message in the message area, above the hint, and use it as the validation message. Set to `null` (the default) or remove the attribute to clear the error." }, { "name": "warning", "property": "warning", "type": "null | string", "default": "null", "description": "Draws a warning-style input with warning colored border and icon. Set to an empty string (or use the bare attribute ``) to render warning styling without a visible message. Set to a non-empty string to additionally display that message in the message area, above the hint. Warnings do not block form submission. Set to `null` (the default) or remove the attribute to clear the warning." }, { "name": "ai", "property": "ai", "type": "boolean", "default": "false", "description": "Draws an ai-style input with AI colored border and icon. Suppressed visually once\n`hasInteracted` flips, but the property and attribute are preserved so the styling\nreturns after `formResetCallback` clears `hasInteracted`." }, { "name": "hint", "property": "hint", "type": "string", "default": "''", "description": "The form control's hint text. If you need to display HTML, use the `hint` slot instead." }, { "name": "disabled", "property": "disabled", "type": "boolean", "description": "Disables the form control. HTML treats a control as disabled when either its own `disabled` is\nset or an ancestor `
` is disabled, so reading this reports the combined state while\nwriting it sets only this element's own. Keeping the two apart is what lets a fieldset be\nre-enabled without clearing a disabled state the consumer set in the meantime." }, { "name": "dir", "property": "dir", "type": "string" }, { "name": "lang", "property": "lang", "type": "string" } ], "properties": [ { "name": "panel", "type": "HTMLElement", "description": "The surface, and the element that scrolls — which is not the list, so keyboard navigation\nhas to scroll this one to bring an option into view." }, { "name": "validationTarget", "type": "undefined | HTMLElement", "description": "Where to anchor native constraint validation" }, { "name": "filter", "type": "((option: EdOption, query: string) => boolean) | null", "description": "A function that customizes how options are filtered based on the input value. The function receives the option and the current input query string. Return true to include the option in the filtered list, false to exclude. By default, options are filtered by checking if the option's label contains the query (case-insensitive). Ignored in server mode, where the server decides what matches." }, { "name": "dataSource", "type": "EdComboboxDataSource | null", "description": "Where a combobox in server mode gets its options from. Handed the query and an `AbortSignal`, it answers with\n`{ value, label, disabled? }` objects or `` elements, which replace the options shown. An answer a\nnewer request overtook is dropped; a failure is reported through `ed-combobox-options-error`." }, { "name": "optionsError", "type": "unknown", "description": "Why the last request for options failed, or null; the panel then shows the `error` slot in place of the list.\nSet when a `dataSource` fails; with `server` alone, set it yourself. The next request sets it back to null.\nNot `error`, which every form control already uses for its validation message." }, { "name": "getTag", "type": "(option: EdOption, index: number) => TemplateResult | string | HTMLElement", "description": "A function that customizes the tags to be rendered when multiple=true. The first argument is the option, the second\nis the current tag's index. Return a Lit `TemplateResult`, an `HTMLElement`, or a string (strings render as text and\nare auto-escaped — to render rich content, return a `TemplateResult` or build an `HTMLElement` yourself). For React,\nwrap JSX with the `jsxToHtml()` helper. For non-Lit vanilla JS, use the re-exported `html` tag." }, { "name": "form", "type": "HTMLFormElement | null", "description": "By default, form controls are associated with the nearest containing `
` element. This attribute allows you\nto place the form control outside of a form and associate it with the form that has this `id`. The form must be in\nthe same document or shadow root for this to work." } ], "methods": [ { "name": "show", "description": "Shows the listbox." }, { "name": "hide", "description": "Hides the listbox." }, { "name": "reload", "returns": "Promise", "description": "Asks the server again for the options, with the text typed since the list opened, or an empty query. With a\n`dataSource` it resolves once the newest answer is applied — where typing overtakes this request, that is the\nanswer to the typing — or once that request fails, which is reported through `ed-combobox-options-error`\ninstead of rejecting. With `server` alone it resolves right after `ed-combobox-options-request`. Removing the\ncombobox resolves it as well. Outside server mode it resolves at once." }, { "name": "focus", "parameters": [ { "name": "options", "type": "FocusOptions", "optional": true } ], "description": "Sets focus on the control." }, { "name": "blur", "description": "Removes focus from the control." }, { "name": "setCustomValidity", "parameters": [ { "name": "message", "type": "string" } ], "description": "Do not use this when creating a \"Validator\". This is intended for end users of components.\nWe track manually defined custom errors so we don't clear them on accident in our validators." }, { "name": "resetValidity", "description": "Reset validity is a way of removing manual custom errors and native validation." } ], "events": [ { "name": "input", "react": "onInput", "type": "InputEvent", "description": "Emitted when the control receives input." }, { "name": "change", "react": "onChange", "type": "Event", "description": "Emitted when the control's value changes." }, { "name": "focus", "react": "onFocus", "description": "Emitted when the control gains focus." }, { "name": "blur", "react": "onBlur", "description": "Emitted when the control loses focus." }, { "name": "ed-clear", "react": "onEdClear", "description": "Emitted when the control's value is cleared." }, { "name": "ed-show", "react": "onEdShow", "description": "Emitted when the select's menu opens. Cancelable; calling `preventDefault()` keeps it closed." }, { "name": "ed-after-show", "react": "onEdAfterShow", "description": "Emitted after the select's menu opens and all animations are complete." }, { "name": "ed-hide", "react": "onEdHide", "description": "Emitted when the select's menu closes. Cancelable; calling `preventDefault()` keeps it open." }, { "name": "ed-after-hide", "react": "onEdAfterHide", "description": "Emitted after the select's menu closes and all animations are complete." }, { "name": "ed-invalid", "react": "onEdInvalid", "description": "Emitted when the form control has been checked for validity and its constraints aren't satisfied." }, { "name": "ed-combobox-options-request", "react": "onEdComboboxOptionsRequest", "type": "EdComboboxOptionsRequestEvent", "description": "Emitted in server mode whenever options are requested: when the list opens, with an empty query; once the typing rests, with the typed text; and on `reload()`. The detail is `{ query, signal }`; the signal aborts once a newer request overtakes it. Emitted with a `dataSource` as well. With `server` alone, answer it by swapping the `` children and setting `loading` to false." }, { "name": "ed-combobox-options-error", "react": "onEdComboboxOptionsError", "type": "EdComboboxOptionsErrorEvent", "description": "Emitted when the `dataSource` fails a request that is still current. The detail is `{ error, request: { query } }`." } ], "slots": [ { "name": "", "description": "The listbox options. Must be `` elements. You can use `` to group items visually. With `tree`, options may be nested to any depth to form a hierarchy." }, { "name": "label", "description": "The input's label. Alternatively, you can use the `label` attribute." }, { "name": "start", "description": "An element, such as ``, placed at the start of the combobox." }, { "name": "end", "description": "An element, such as ``, placed at the end of the combobox." }, { "name": "clear-icon", "description": "An icon to use in lieu of the default clear icon." }, { "name": "no-results", "description": "Content shown when no option matches the current input. Rendered outside the listbox, because an inert hint is not a selectable option. Alternatively, use the no-results-label attribute for plain text." }, { "name": "empty", "description": "Content shown in server mode when the server has no options for an empty query. Its text is announced." }, { "name": "loading", "description": "Content shown in server mode while options are being requested and none are showing. Its text is announced." }, { "name": "error", "description": "Content shown in server mode when the last request for options failed, in place of the list. Its text is announced." }, { "name": "expand-icon", "description": "The icon to show when the control is expanded and collapsed. Rotates on open and close." }, { "name": "hint", "description": "Text that describes how to use the input. Alternatively, you can use the `hint` attribute." } ], "cssProperties": [ { "name": "--ed-show-duration", "default": "var(--ed-transition-fast)", "description": "The duration of the show animation." }, { "name": "--ed-hide-duration", "default": "var(--ed-transition-fast)", "description": "The duration of the hide animation." }, { "name": "--ed-combobox-tag-max-size", "default": "10ch", "description": "When using `multiple`, the max size of tags before their content is truncated." } ], "parts": [ { "name": "form-control", "description": "The form control that wraps the label, input, and hint." }, { "name": "form-control-label", "description": "The label's wrapper." }, { "name": "form-control-input", "description": "The select's wrapper." }, { "name": "message", "description": "The state message: an error, a warning, or the AI note." }, { "name": "hint", "description": "The hint's wrapper." }, { "name": "combobox", "description": "The container the wraps the start, end, value, clear icon, and expand button." }, { "name": "base", "description": "The bordered field box. An alias for `input`, so a selector written against another form control reaches the same element here." }, { "name": "input", "description": "The element carrying the field's border and background." }, { "name": "expand-icon-slot", "description": "The slot holding the expand icon." }, { "name": "start", "description": "The container that wraps the `start` slot." }, { "name": "end", "description": "The container that wraps the `end` slot." }, { "name": "display-input", "description": "The element that displays the selected option's label, an `` element." }, { "name": "panel", "description": "The floating surface, carrying the frame, background and shadow. It holds the option list while something matches and the no-match message once nothing does, so one selector reaches the dropdown in either state. Sizing it past the field's own width is not corrected when the field sits near a viewport edge: the popup is positioned on its own box, which `sync=\"width\"` pins to the field, so collision handling never sees the wider child." }, { "name": "listbox", "description": "The scrolling list of options inside the panel. Use it for the list itself — its height, or how far it scrolls — rather than for the dropdown's framing. A height belongs here and not on `panel`: the panel clips to its own corners, so limiting its height cuts options off instead of scrolling them." }, { "name": "listbox-tree", "description": "Added to the list when `tree` is set and it carries role=\"tree\"." }, { "name": "status", "description": "The message sitting in the panel in place of the list, whichever it is. Also carries the part of its kind." }, { "name": "no-results", "description": "The message shown when nothing matches, sitting in the panel in place of the list." }, { "name": "empty", "description": "The message shown in server mode when there are no options for an empty query." }, { "name": "loading", "description": "The message shown in server mode while options load and none are showing." }, { "name": "error", "description": "The message shown in server mode when the last request for options failed." }, { "name": "tags", "description": "The container that houses option tags when `multiselect` is used." }, { "name": "tag", "description": "The individual tags that represent each multiselect option." }, { "name": "tag__base", "description": "The tag's exported `base` part, the badge's surface." }, { "name": "tag__remove-icon", "description": "The tag's exported `remove-icon` part, the `