{ "tag": "ed-tag-input", "kind": "component", "summary": "Tag inputs collect a list of short values, such as keywords, email addresses or labels, as removable tags.\nUsers add a tag by typing and pressing Enter or a delimiter, and each tag is submitted as its own form value.", "status": "experimental", "level": "atom", "since": "1.0", "docs": "https://test-apps.eurodata.de/a/eurodata-ui/docs/components/tag-input/", "usage": "https://test-apps.eurodata.de/a/eurodata-ui/docs/components/tag-input/usage/", "playwright": "getByTestId('…').getByRole('textbox')", "dependencies": [ "ed-badge", "ed-icon" ], "use": [ "Entering a list of short values, such as email addresses to notify or keywords for a document, each shown as a removable tag", "A field where the user types a value and presses Enter or a comma to add several entries one after another", "Collecting labels on a record, with a minimum or maximum number of tags and a check that rejects duplicates", "Recipients of a message or report, where each address is submitted as its own value with the form" ], "notFor": [ { "when": "Choosing from a fixed list of predefined options", "instead": "a [Select](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/select) with multiple, or a [Combobox](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/combobox) for long lists" }, { "when": "One free-text value such as a name or a reference number", "instead": "an [Input](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/input)" }, { "when": "Long free-form text over several lines", "instead": "a [Textarea](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/textarea)" } ], "rules": [ { "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": "value", "property": "defaultValue", "type": "null | string", "description": "The default value of the form control as a delimiter-separated string. Primarily used for resetting the form\ncontrol." }, { "name": "delimiter", "property": "delimiter", "type": "string", "default": "','", "description": "The characters that turn typed text into a tag. Each character is a separate delimiter, so `\",;\"` accepts both\ncommas and semicolons. Pasted text is split on the same characters. Set to an empty string so only Enter adds a\ntag. Also used to parse the `value` attribute, which falls back to a comma when the delimiter is empty." }, { "name": "max-tags", "property": "maxTags", "type": "number", "description": "The maximum number of tags that can be added. Once reached, no more tags can be added until one is removed." }, { "name": "min-tags", "property": "minTags", "type": "number", "description": "The minimum number of tags required for the control to be valid. Has no effect when there are no tags." }, { "name": "allow-duplicates", "property": "allowDuplicates", "type": "boolean", "default": "false", "description": "Allows the same tag to be added more than once. By default, duplicates are ignored." }, { "name": "with-clear", "property": "withClear", "type": "boolean", "default": "false", "description": "Adds a clear button that removes all tags, and makes Escape empty the control." }, { "name": "placeholder", "property": "placeholder", "type": "string", "default": "''", "description": "Placeholder text to show in the text box. Hidden once the maximum number of tags is reached." }, { "name": "label", "property": "label", "type": "string", "default": "''", "description": "The tag input'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 tag input's accessible name for when no visible label is set. Mirrored onto the internal text box, where the\ntextbox role lives, and onto the list of tags." }, { "name": "with-label", "property": "withLabel", "type": "boolean", "default": "false", "description": "Only required for SSR. Set to `true` if you're slotting in a `label` element so the server-rendered markup\nincludes the label before the component hydrates on the client." }, { "name": "with-hint", "property": "withHint", "type": "boolean", "default": "false", "description": "Only required for SSR. Set to `true` if you're slotting in a `hint` element so the server-rendered markup\nincludes the hint before the component hydrates on the client." }, { "name": "density", "property": "density", "type": "'compact' | 'default' | 'spacious'", "default": "'default'", "description": "Controls the component's spacing density without affecting font-size." }, { "name": "pill", "property": "pill", "type": "boolean", "default": "false", "description": "Draws a pill-style tag input with rounded edges. The tags are pill-shaped either way." }, { "name": "readonly", "property": "readonly", "type": "boolean", "default": "false", "description": "Makes the tag input readonly. Tags stay visible and are still submitted, but can't be added or removed." }, { "name": "required", "property": "required", "type": "boolean", "default": "false", "description": "Makes the tag input a required field, so at least one tag must be added." }, { "name": "autocapitalize", "property": "autocapitalize", "type": "'none' | 'off' | 'on' | 'sentences' | 'words' | 'characters'", "description": "Controls whether and how text input is automatically capitalized as it is entered by the user." }, { "name": "autocorrect", "property": "autocorrect", "type": "boolean", "description": "Indicates whether the browser's autocorrect feature is on or off. When set as an attribute, use `\"off\"` or `\"on\"`.\nWhen set as a property, use `true` or `false`." }, { "name": "autocomplete", "property": "autocomplete", "type": "string", "description": "Specifies what permission the browser has to provide assistance in filling out form field values. Refer to\n[this page on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete) for available values.\nDefaults to `off`." }, { "name": "enterkeyhint", "property": "enterkeyhint", "type": "'next' | 'previous' | 'search' | 'send' | 'done' | 'enter' | 'go'", "description": "Used to customize the label or icon of the Enter key on virtual keyboards." }, { "name": "spellcheck", "property": "spellcheck", "type": "boolean", "default": "true", "description": "Enables spell checking on the text box." }, { "name": "inputmode", "property": "inputmode", "type": "'search' | 'text' | 'numeric' | 'none' | 'email' | 'tel' | 'url' | 'decimal'", "description": "Tells the browser what type of data will be entered by the user, allowing it to display the appropriate virtual\nkeyboard on supportive devices." }, { "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": "name", "property": "name", "type": "null | string", "default": "null", "description": "The name of the input, submitted as a name/value pair with form data." }, { "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": "value", "type": "string[]", "description": "The tags as an array of strings, submitted as one entry per tag under `name`. Set the `value` attribute to a\ndelimiter-separated string for an initial value." }, { "name": "inputValue", "type": "string", "description": "The text currently typed in the text box that hasn't become a tag yet." }, { "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." }, { "name": "validationTarget", "type": "undefined | HTMLElement", "description": "Override this to change where constraint validation popups are anchored." } ], "methods": [ { "name": "focus", "parameters": [ { "name": "options", "type": "FocusOptions", "optional": true } ], "description": "Sets focus on the text box." }, { "name": "blur", "description": "Removes focus from the text box." }, { "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 user types in the text box or when a tag is added or removed." }, { "name": "change", "react": "onChange", "type": "Event", "description": "Emitted when a tag is added, removed, or all tags are cleared by the user." }, { "name": "blur", "react": "onBlur", "description": "Emitted when the control loses focus." }, { "name": "focus", "react": "onFocus", "description": "Emitted when the control gains focus." }, { "name": "ed-tag-input-create", "react": "onEdTagInputCreate", "type": "EdTagInputCreateEvent", "description": "Emitted before typed text becomes a tag. Cancelable; calling `preventDefault()` rejects it. `detail.inputValue` is the trimmed text that would become the tag." }, { "name": "ed-clear", "react": "onEdClear", "description": "Emitted when the tags are cleared by the clear button or by Escape." }, { "name": "ed-invalid", "react": "onEdInvalid", "description": "Emitted when the form control has been checked for validity and its constraints aren't satisfied." } ], "slots": [ { "name": "label", "description": "The tag input's label. Alternatively, you can use the `label` attribute." }, { "name": "start", "description": "An element, such as ``, placed at the start of the control." }, { "name": "end", "description": "An element, such as ``, placed at the end of the control." }, { "name": "clear-icon", "description": "An icon to use in lieu of the default clear icon." }, { "name": "hint", "description": "Text that describes how to use the tag input. Alternatively, you can use the `hint` attribute." } ], "cssProperties": [], "parts": [ { "name": "form-control-label", "description": "The label." }, { "name": "label", "description": "The label. The same element as `form-control-label`, named like the label of ``." }, { "name": "tag-input", "description": "The bordered box that holds the tags and the text box." }, { "name": "start", "description": "The container that wraps the `start` slot." }, { "name": "tags", "description": "The list that holds the tags." }, { "name": "tag", "description": "Each tag, an ``." }, { "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 `