Tag Input
<wa-tag-input>
Tag inputs collect a list of short values, such as keywords, email addresses, or labels, as removable tags. Users add a tag by typing and pressing Enter or a delimiter, and each tag is submitted as its own form value.
This component works with standard <form> elements. See form controls for form submission and client-side validation.
Examples
Label
Use the label attribute to give the tag input an accessible label. For labels that contain HTML, use the label slot instead.
Hint
Add a descriptive hint with the hint attribute. For hints that contain HTML, use the hint slot instead.
Placeholder
Use the placeholder attribute to show prompt text in the text box. The placeholder is hidden once the maximum number of tags is reached.
Initial Value
Use the value attribute to start with a list of tags. Separate each tag with the delimiter, a comma by default.
Framework users can bind directly to the value property, an array of strings.
Delimiter
Use the delimiter attribute to change which characters turn typed text into a tag. Each character in the string is a separate delimiter, and pasted text is split on the same characters. Set it to an empty string so only Enter adds a tag.
Text left in the text box becomes a tag when the tag input loses focus. Text that can't become a tag is discarded.
Pasting
Pasting delimiter-separated text adds a tag for each value in one step. The same rules apply as when typing, so values that can't become tags, such as duplicates and anything past max-tags, stay in the text box instead of being lost. Pasted text without a delimiter is inserted as ordinary text.
Clearable
Add the with-clear attribute to show a button that removes every tag at once. The button only appears once there is at least one tag.
Max Tags
Use the max-tags attribute to cap the number of tags. Once the limit is reached, no more tags can be added until one is removed.
Allowing Duplicates
Duplicate tags are ignored by default. Add the allow-duplicates attribute to let the same value appear more than once.
Appearance
Use the appearance attribute to change the tag input's visual style.
Pill
Use the pill attribute to give the tag input and its tags rounded edges.
Size
Use the size attribute to change the tag input's size. The tags scale with it.
Disabled
Use the disabled attribute to disable a tag input.
Readonly
Use the readonly attribute to show tags that can't be changed. Unlike disabled, a readonly tag input stays focusable and its value is still submitted with the form.
Start & End Decorations
Use the start and end slots to add presentational elements such as <wa-icon> inside the tag input.
Validation
Add the required attribute to require at least one tag. Use the min-tags and max-tags attributes to validate the number of tags. min-tags only applies once there is at least one tag, so pair it with required to make tags mandatory. max-tags also prevents adding more.
Custom Validity
Use the setCustomValidity() method to set a custom validation message. This will prevent the form from submitting and make the browser display the error message you provide. To clear the error, call this function with an empty string.
Rejecting Tags
The wa-create event fires before typed text becomes a tag. Call event.preventDefault() to reject it, for example to enforce a format.
Tell people why a tag was rejected.
Rejecting a tag produces no message of its own. Update the hint or call setCustomValidity() from your listener so the reason reaches screen readers too.
Reacting to Changes
Listen for the change event to respond when a tag is added or removed. The value property holds the current list.
Labels: bug, help wanted
Customizing
Use CSS parts to style the tags and the text box.
Accessibility Considerations
The tags are exposed to assistive technology as a list, and each tag's remove button is labeled. A focused tag carries a hidden description explaining that Backspace or Delete removes it. Additions, removals, rejected duplicates, and clearing all tags are announced to screen readers. Always provide a label with the label attribute or slot; without one, the text box has no accessible name.
Tags are reachable with the arrow keys rather than Tab, so the control takes a single tab stop:
| Key | Behavior |
|---|---|
| Enter | Adds the typed text as a tag. With an empty text box, submits the form. |
| Delimiter (, by default) | Adds the text before it as a tag |
| Backspace | With an empty text box, removes the last tag. On a focused tag, removes it and focuses the previous one. |
| Delete | On a focused tag, removes it and focuses the next one |
| ← → | From an empty text box, ← focuses the last tag. Moves between tags, and → from the last tag returns to the text box. |
| Home End | On a focused tag, Home focuses the first tag and End returns to the text box |
| Escape | Clears the typed text. On a focused tag, returns to the text box. |
In right-to-left languages, the arrow keys follow the reading direction, so → moves toward the start of the list and ← moves toward the text box.
API
Importing
If you're using the autoloader or a hosted project, components load on demand — no manual import needed. To cherry-pick a component manually, use one of the following snippets.
Import this component directly from the CDN:
import 'https://ka-f.webawesome.com/[email protected]/components/tag-input/tag-input.js';
After installing Web Awesome via npm, import this component:
import '@awesome.me/webawesome/dist/components/tag-input/tag-input.js';
If you're self-hosting Web Awesome, import this component from your server:
import './webawesome/dist/components/tag-input/tag-input.js';
To import this component for React 18 or below, use the following code:
import WaTagInput from '@awesome.me/webawesome/dist/react/tag-input/index.js';
Slots
Learn more about using slots.
| Name | Description |
|---|---|
clear-icon
|
An icon to use in lieu of the default clear icon. |
end
|
An element, such as <wa-icon>, placed at the end of the control. |
hint
|
Text that describes how to use the tag input. Alternatively, you can use the hint attribute. |
label
|
The tag input's label. Alternatively, you can use the label attribute. |
start
|
An element, such as <wa-icon>, placed at the start of the control. |
Attributes & Properties
Learn more about attributes and properties.
| Name | Description | Reflects |
|---|---|---|
allowDuplicatesallow-duplicates |
Allows the same tag to be added more than once. By default, duplicates are ignored.
Type
boolean
Default
false
|
|
appearanceappearance |
The tag input's visual appearance.
Type
'filled' | 'outlined' | 'filled-outlined'
Default
'outlined'
|
|
autocapitalizeautocapitalize |
Controls whether and how text input is automatically capitalized as it is entered by the user.
Type
'off' | 'none' | 'on' | 'sentences' | 'words' | 'characters'
|
|
autocompleteautocomplete |
Specifies what permission the browser has to provide assistance in filling out form field values. Refer to
this page on MDN for available values.
Defaults to
off.
Type
string
|
|
autocorrectautocorrect |
Indicates whether the browser's autocorrect feature is on or off. When set as an attribute, use
"off" or "on".
When set as a property, use true or false.
Type
boolean
|
|
defaultValuevalue |
The default value of the form control as a delimiter-separated string. Primarily used for resetting the form
control.
Type
string | null
|
|
delimiterdelimiter |
The characters that turn typed text into a tag. Each character is a separate delimiter, so
",;" accepts both
commas and semicolons. Pasted text is split on the same characters. Set to an empty string so only Enter adds a
tag. Also used to parse the value attribute, which falls back to a comma when the delimiter is empty.
Type
string
Default
','
|
|
disableddisabled |
Disables the form control.
Type
boolean
Default
false
|
|
enterkeyhintenterkeyhint |
Used to customize the label or icon of the Enter key on virtual keyboards.
Type
'enter' | 'done' | 'go' | 'next' | 'previous' | 'search' | 'send'
|
|
form |
By default, form controls are associated with the nearest containing
<form> element. This attribute allows you
to place the form control outside of a form and associate it with the form that has this id. The form must be in
the same document or shadow root for this to work.
Type
HTMLFormElement | null
|
|
hinthint |
The tag input's hint. If you need to display HTML, use the
hint slot instead.
Type
string
Default
''
|
|
inputmodeinputmode |
Tells the browser what type of data will be entered by the user, allowing it to display the appropriate virtual
keyboard on supportive devices.
Type
'none' | 'text' | 'decimal' | 'numeric' | 'tel' | 'search' | 'email' | 'url'
|
|
inputValue |
The text currently typed in the text box that hasn't become a tag yet.
Type
string
Default
''
|
|
labellabel |
The tag input's label. If you need to display HTML, use the
label slot instead.
Type
string
Default
''
|
|
maxTagsmax-tags |
The maximum number of tags that can be added. Once reached, no more tags can be added until one is removed.
Type
number
|
|
minTagsmin-tags |
The minimum number of tags required for the control to be valid. Has no effect when there are no tags.
Type
number
|
|
namename |
The name of the input, submitted as a name/value pair with form data.
Type
string | null
Default
null
|
|
pillpill |
Draws a pill-style tag input, and pill-style tags, with rounded edges.
Type
boolean
Default
false
|
|
placeholderplaceholder |
Placeholder text to show in the text box. Hidden once the maximum number of tags is reached.
Type
string
Default
''
|
|
readonlyreadonly |
Makes the tag input readonly. Tags stay visible and are still submitted, but can't be added or removed.
Type
boolean
Default
false
|
|
requiredrequired |
Makes the tag input a required field, so at least one tag must be added.
Type
boolean
Default
false
|
|
sizesize |
The tag input's size. Also applied to each tag.
Type
'xs' | 's' | 'm' | 'l' | 'xl' | 'small' | 'medium' | 'large'
Default
'm'
|
|
spellcheckspellcheck |
Enables spell checking on the text box.
Type
boolean
Default
true
|
|
validationTarget |
Override this to change where constraint validation popups are anchored.
Type
undefined | HTMLElement
|
|
validators |
Validators are static because they have
observedAttributes, essentially attributes to "watch"
for changes. Whenever these attributes change, we want to be notified and update the validator.
Type
Validator[]
Default
[]
|
|
value |
The tags as an array of strings, submitted as one entry per tag under
name. Set the value attribute to a
delimiter-separated string for an initial value.
Type
string[]
|
|
withClearwith-clear |
Adds a clear button that removes all tags.
Type
boolean
Default
false
|
|
withHintwith-hint |
Only required for SSR. Set to
true if you're slotting in a hint element so the server-rendered markup
includes the hint before the component hydrates on the client.
Type
boolean
Default
false
|
|
withLabelwith-label |
Only required for SSR. Set to
true if you're slotting in a label element so the server-rendered markup
includes the label before the component hydrates on the client.
Type
boolean
Default
false
|
Methods
Learn more about methods.
| Name | Description | Arguments |
|---|---|---|
blur() |
Removes focus from the text box. | |
focus() |
Sets focus on the text box. |
options: FocusOptions
|
formStateRestoreCallback() |
Called when the browser is trying to restore element’s state to state in which case reason is "restore", or when the browser is trying to fulfill autofill on behalf of user in which case reason is "autocomplete". In the case of "restore", state is a string, File, or FormData object previously set as the second argument to setFormValue. |
state: string | File | FormData | null,
reason: 'autocomplete' | 'restore'
|
resetValidity() |
Reset validity is a way of removing manual custom errors and native validation. | |
setCustomValidity() |
Do not use this when creating a "Validator". This is intended for end users of components. We track manually defined custom errors so we don't clear them on accident in our validators. |
message: string
|
Events
Learn more about events.
| Name | Description |
|---|---|
blur |
Emitted when the control loses focus. |
change |
Emitted when a tag is added, removed, or all tags are cleared by the user. |
focus |
Emitted when the control gains focus. |
input |
Emitted when the user types in the text box or when a tag is added or removed. |
wa-clear |
Emitted when the clear button is activated. |
wa-create |
Emitted before typed text becomes a tag. Call event.preventDefault() to reject it. The event detail contains { inputValue: string }, the text that would become the tag. |
wa-invalid |
Emitted when the form control has been checked for validity and its constraints aren't satisfied. |
Custom States
Learn more about custom states.
| Name | Description | CSS selector |
|---|---|---|
blank |
The tag input has no tags. |
:state(blank)
|
readonly |
The tag input is readonly. |
:state(readonly)
|
CSS Parts
Learn more about CSS parts.
| Name | Description | CSS selector |
|---|---|---|
clear-button |
The clear button. |
::part(clear-button)
|
end |
The container that wraps the end slot. |
::part(end)
|
form-control-label |
The label. |
::part(form-control-label)
|
hint |
The hint's wrapper. |
::part(hint)
|
input |
The internal text box, an <input> element. |
::part(input)
|
start |
The container that wraps the start slot. |
::part(start)
|
tag |
Each tag, a <wa-tag>. |
::part(tag)
|
tag__content |
The tag's content part. |
::part(tag__content)
|
tag__remove-button |
The tag's remove button. |
::part(tag__remove-button)
|
tag__remove-button__base |
The tag's remove button base part. |
::part(tag__remove-button__base)
|
tag-input |
The component's outer wrapper, the bordered box that holds the tags and text box. |
::part(tag-input)
|
tags |
The list that holds the tags. |
::part(tags)
|
Dependencies
This component automatically imports the following elements. Sub-dependencies, if any exist, will also be included in this list.