Font Awesome Build Awesome
Try SSR Server-side rendering (SSR) generates component HTML on the server before the page loads, improving SEO and initial load time. Use the switch to see Web Awesome components render with and without SSR.
Search this website ⌘KCtrl+K Light Dark System Docs Select Color Scheme Default Awesome Shoelace Active Brutalist Glossy Matter Mellow Playful Premium Tailspin Docs Select Theme View Project on GitHub Star Project on GitHub
Start Components Docs Help Pro
Login Log into your account
Web Awesome Font Awesome Build Awesome
Search this site… /
Try SSR Server-side rendering (SSR) generates component HTML on the server before the page loads, improving SEO and initial load time. Use the switch to see Web Awesome components render with and without SSR.
Light Dark System Docs Select Color Scheme Default Awesome Shoelace Active Brutalist Glossy Matter Mellow Playful Premium Tailspin Docs Select Theme

Getting Started

  • Installation
  • Usage
  • Forms
  • Localization
  • Frameworks
  • Using with AI
  • Figma Design Kit ProThis requires access to Web Awesome Pro
  • Server Rendering

Resources

  • Accessibility
  • Browser Support
  • Contributing
  • Patterns ProPatterns require access to Web Awesome Pro
  • Migrating from Shoelace
  • Visual Tests
  • Changelog
  • Help & Support

Theming & Utilities

  • Overview
  • Built-in Themes
  • Color Palettes
  • Design Tokens
  • Customizing & Theming
  • CSS Utilities

Actions

  • Button
  • Button Group
  • Copy Button
  • Dropdown
    • Dropdown Item

Forms

  • Checkbox
  • Checkbox Group
  • Color Picker
  • Combobox ProThis requires access to Web Awesome Pro
  • Date Input ProThis requires access to Web Awesome Pro
  • Date Picker ProThis requires access to Web Awesome Pro
  • File Input ProThis requires access to Web Awesome Pro
  • Input
  • Known Date
  • Number Input
  • OTP Input
  • Radio Group
    • Radio
  • Rating
  • Select
    • Option
  • Slider
  • Switch
  • Tag Input
  • Textarea
  • Time Input

Layout

  • Accordion
    • Accordion Item
  • Card
  • Details
  • Dialog
  • Divider
  • Drawer
  • Page
  • Scroller
  • Split Panel

Navigation

  • Breadcrumb
    • Breadcrumb Item
  • Pagination
  • Tab Group
    • Tab
    • Tab Panel
  • Tree
    • Tree Item

Feedback

  • Badge
  • Callout
  • Progress Bar
  • Progress Ring
  • Skeleton
  • Spinner
  • Tag
  • Toast
    • Toast Item
  • Tooltip

Media

  • Animated Image
  • Avatar
  • Carousel
    • Carousel Item
  • Comparison
  • Icon
  • Markdown
  • QR Code
  • Video ProThis requires access to Web Awesome Pro
  • Video Playlist ProThis requires access to Web Awesome Pro
  • Zoomable Frame

Data Viz ProThis requires access to Web Awesome Pro

  • Bar Chart
  • Bubble Chart
  • Data Grid
  • Doughnut Chart
  • Line Chart
  • Pie Chart
  • Polar Area Chart
  • Radar Chart
  • Scatter Chart
  • Sparkline
  • Advanced Usage

Helpers

  • Animation
  • Format Bytes
  • Format Date
  • Format Number
  • Include
  • Intersection Observer
  • Mutation Observer
  • Popover
  • Popup
  • Random Content
  • Relative Time
  • Resize Observer

Tag Input

  • Examples
  • Label
  • Hint
  • Placeholder
  • Initial Value
  • Delimiter
  • Pasting
  • Clearable
  • Max Tags
  • Allowing Duplicates
  • Appearance
  • Pill
  • Size
  • Disabled
  • Readonly
  • Start & End Decorations
  • Validation
  • Custom Validity
  • Rejecting Tags
  • Reacting to Changes
  • Customizing
  • Accessibility Considerations
  • API
  • Importing
  • Slots
  • Attributes & Properties
  • Methods
  • Events
  • Custom States
  • CSS Parts
  • Dependencies
On This Page...
  • Examples
  • Label
  • Hint
  • Placeholder
  • Initial Value
  • Delimiter
  • Pasting
  • Clearable
  • Max Tags
  • Allowing Duplicates
  • Appearance
  • Pill
  • Size
  • Disabled
  • Readonly
  • Start & End Decorations
  • Validation
  • Custom Validity
  • Rejecting Tags
  • Reacting to Changes
  • Customizing
  • Accessibility Considerations
  • API
  • Importing
  • Slots
  • Attributes & Properties
  • Methods
  • Events
  • Custom States
  • CSS Parts
  • Dependencies

Tag Input

<wa-tag-input>
Experimental Forms Since 3.13

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.

<wa-tag-input label="Keywords" placeholder="Add a keyword" value="design, accessibility"></wa-tag-input>
<wa-tag-input label="Topics" hint="Press Enter or type a comma after each topic." value="Design, CSS" with-clear>
  <wa-icon slot="start" name="tag"></wa-icon>
</wa-tag-input>

This component works with standard <form> elements. See form controls for form submission and client-side validation.

Examples

Link to This Section

Label

Link to This Section

Use the label attribute to give the tag input an accessible label. For labels that contain HTML, use the label slot instead.

<wa-tag-input label="Skills"></wa-tag-input>

Hint

Link to This Section

Add a descriptive hint with the hint attribute. For hints that contain HTML, use the hint slot instead.

<wa-tag-input label="Ingredients" hint="Press Enter or type a comma after each ingredient."></wa-tag-input>

Placeholder

Link to This Section

Use the placeholder attribute to show prompt text in the text box. The placeholder is hidden once the maximum number of tags is reached.

<wa-tag-input label="Guest list" placeholder="Add a name"></wa-tag-input>

Initial Value

Link to This Section

Use the value attribute to start with a list of tags. Separate each tag with the delimiter, a comma by default.

<wa-tag-input label="Toppings" value="Mushrooms, Olives, Peppers"></wa-tag-input>

Framework users can bind directly to the value property, an array of strings.

Delimiter

Link to This Section

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.

<div class="wa-stack">
  <wa-tag-input label="Space-separated" delimiter=" " placeholder="Type a word and a space"></wa-tag-input>
  <wa-tag-input label="Commas or semicolons" delimiter=",;" placeholder="Type a value and , or ;"></wa-tag-input>
  <wa-tag-input label="Enter only" delimiter="" placeholder="Type a value and press Enter"></wa-tag-input>
</div>

Pasting

Link to This Section

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.

Copy spices
<wa-copy-button value="Cumin, Paprika, Coriander, Turmeric">
  <wa-button appearance="filled">
    <wa-icon slot="start" name="clipboard"></wa-icon>
    Copy spices
  </wa-button>
</wa-copy-button>

<wa-divider></wa-divider>

<wa-tag-input label="Spices" placeholder="Paste the copied list here"></wa-tag-input>

Clearable

Link to This Section

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.

<wa-tag-input label="Tickers" value="AAPL, MSFT, NVDA" with-clear></wa-tag-input>

Max Tags

Link to This Section

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.

<wa-tag-input
  label="Desert island albums"
  hint="Choose up to three."
  value="Kind of Blue, Rumours"
  max-tags="3"
  placeholder="Add an album"
></wa-tag-input>

Allowing Duplicates

Link to This Section

Duplicate tags are ignored by default. Add the allow-duplicates attribute to let the same value appear more than once.

<wa-tag-input label="Dice rolls" value="6, 6" allow-duplicates placeholder="Roll again"></wa-tag-input>

Appearance

Link to This Section

Use the appearance attribute to change the tag input's visual style.

<div class="wa-stack">
  <wa-tag-input appearance="outlined" value="Outlined" label="Outlined"></wa-tag-input>
  <wa-tag-input appearance="filled" value="Filled" label="Filled"></wa-tag-input>
  <wa-tag-input appearance="filled-outlined" value="Filled outlined" label="Filled outlined"></wa-tag-input>
</div>

Pill

Link to This Section

Use the pill attribute to give the tag input and its tags rounded edges.

<wa-tag-input label="Interests" value="Hiking, Chess" pill></wa-tag-input>

Size

Link to This Section

Use the size attribute to change the tag input's size. The tags scale with it.

<div class="wa-stack">
  <wa-tag-input size="xs" label="Extra small" value="Extra small"></wa-tag-input>
  <wa-tag-input size="s" label="Small" value="Small"></wa-tag-input>
  <wa-tag-input size="m" label="Medium" value="Medium"></wa-tag-input>
  <wa-tag-input size="l" label="Large" value="Large"></wa-tag-input>
  <wa-tag-input size="xl" label="Extra large" value="Extra large"></wa-tag-input>
</div>

Disabled

Link to This Section

Use the disabled attribute to disable a tag input.

<wa-tag-input label="Assignees" value="Ada, Grace" disabled></wa-tag-input>

Readonly

Link to This Section

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.

<wa-tag-input label="Roles" value="Owner, Maintainer" readonly></wa-tag-input>

Start & End Decorations

Link to This Section

Use the start and end slots to add presentational elements such as <wa-icon> inside the tag input.

<div class="wa-stack">
  <wa-tag-input label="Recipients" placeholder="Add an email">
    <wa-icon slot="start" name="envelope"></wa-icon>
  </wa-tag-input>
  <wa-tag-input label="Keywords" placeholder="Add a keyword">
    <wa-icon slot="start" name="tag"></wa-icon>
    <wa-icon slot="end" name="circle-info"></wa-icon>
  </wa-tag-input>
</div>

Validation

Link to This Section

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.


Submit Reset
<form class="tag-input-validation">
  <wa-tag-input
    name="tags"
    label="Tags"
    hint="Add between two and five tags."
    min-tags="2"
    max-tags="5"
    required
  ></wa-tag-input>
  <br />
  <wa-button appearance="filled" type="submit">Submit</wa-button>
  <wa-button type="reset">Reset</wa-button>
</form>

<script type="module">
  const form = document.querySelector('.tag-input-validation');

  form.addEventListener('submit', event => {
    event.preventDefault();
    alert(`Submitted: ${new FormData(form).getAll('tags').join(', ')}`);
  });
</script>

Custom Validity

Link to This Section

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.


Send invites
<form class="tag-input-custom-validity">
  <wa-tag-input
    name="emails"
    label="Invite"
    hint="Every tag must be an email address."
    placeholder="[email protected]"
  ></wa-tag-input>
  <br />
  <wa-button appearance="filled" type="submit">Send invites</wa-button>
</form>

<script type="module">
  const form = document.querySelector('.tag-input-custom-validity');
  const tagInput = form.querySelector('wa-tag-input');

  tagInput.addEventListener('change', () => {
    const invalid = tagInput.value.filter(tag => !tag.includes('@'));
    tagInput.setCustomValidity(invalid.length ? `Not an email address: ${invalid.join(', ')}` : '');
  });

  form.addEventListener('submit', event => {
    event.preventDefault();
    alert('Invites sent');
  });
</script>

Rejecting Tags

Link to This Section

The wa-create event fires before typed text becomes a tag. Call event.preventDefault() to reject it, for example to enforce a format.

<wa-tag-input
  class="tag-input-reject"
  label="Usernames"
  hint="Letters, numbers, and underscores only."
  placeholder="Add a username"
></wa-tag-input>

<script type="module">
  const tagInput = document.querySelector('.tag-input-reject');

  tagInput.addEventListener('wa-create', event => {
    if (!/^\w+$/.test(event.detail.inputValue)) {
      event.preventDefault();
    }
  });
</script>

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

Link to This Section

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

<div class="tag-input-changes">
  <wa-tag-input label="Labels" value="bug, help wanted"></wa-tag-input>
  <p>Labels: <code class="output">bug, help wanted</code></p>
</div>

<script type="module">
  const container = document.querySelector('.tag-input-changes');
  const tagInput = container.querySelector('wa-tag-input');
  const output = container.querySelector('.output');

  tagInput.addEventListener('change', () => {
    output.textContent = tagInput.value.join(', ') || '(none)';
  });
</script>

Customizing

Link to This Section

Use CSS parts to style the tags and the text box.

<wa-tag-input class="tag-input-styled" label="Genres" value="Jazz, Ambient, Techno"></wa-tag-input>

<style>
  .tag-input-styled::part(tag) {
    background-color: var(--wa-color-brand-fill-quiet);
    border-color: var(--wa-color-brand-border-quiet);
    color: var(--wa-color-brand-on-quiet);
  }

  .tag-input-styled::part(tag__remove-button) {
    color: var(--wa-color-brand-on-quiet);
  }
</style>

Accessibility Considerations

Link to This Section

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

Link to This Section

Importing

Link to This Section

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.

CDN npm Self-Hosted React

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

Link to This Section

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

Link to This Section

Learn more about attributes and properties.

Name Description Reflects
allowDuplicates
allow-duplicates
Allows the same tag to be added more than once. By default, duplicates are ignored.
Type boolean
Default false
appearance
appearance
The tag input's visual appearance.
Type 'filled' | 'outlined' | 'filled-outlined'
Default 'outlined'
autocapitalize
autocapitalize
Controls whether and how text input is automatically capitalized as it is entered by the user.
Type 'off' | 'none' | 'on' | 'sentences' | 'words' | 'characters'
autocomplete
autocomplete
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
autocorrect
autocorrect
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
defaultValue
value
The default value of the form control as a delimiter-separated string. Primarily used for resetting the form control.
Type string | null
delimiter
delimiter
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 ','
disabled
disabled
Disables the form control.
Type boolean
Default false
enterkeyhint
enterkeyhint
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
hint
hint
The tag input's hint. If you need to display HTML, use the hint slot instead.
Type string
Default ''
inputmode
inputmode
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 ''
label
label
The tag input's label. If you need to display HTML, use the label slot instead.
Type string
Default ''
maxTags
max-tags
The maximum number of tags that can be added. Once reached, no more tags can be added until one is removed.
Type number
minTags
min-tags
The minimum number of tags required for the control to be valid. Has no effect when there are no tags.
Type number
name
name
The name of the input, submitted as a name/value pair with form data.
Type string | null
Default null
pill
pill
Draws a pill-style tag input, and pill-style tags, with rounded edges.
Type boolean
Default false
placeholder
placeholder
Placeholder text to show in the text box. Hidden once the maximum number of tags is reached.
Type string
Default ''
readonly
readonly
Makes the tag input readonly. Tags stay visible and are still submitted, but can't be added or removed.
Type boolean
Default false
required
required
Makes the tag input a required field, so at least one tag must be added.
Type boolean
Default false
size
size
The tag input's size. Also applied to each tag.
Type 'xs' | 's' | 'm' | 'l' | 'xl' | 'small' | 'medium' | 'large'
Default 'm'
spellcheck
spellcheck
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[]
withClear
with-clear
Adds a clear button that removes all tags.
Type boolean
Default false
withHint
with-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
withLabel
with-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

Link to This Section

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

Link to This Section

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

Link to This Section

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

Link to This Section

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

Link to This Section

This component automatically imports the following elements. Sub-dependencies, if any exist, will also be included in this list.

  • <wa-button>
  • <wa-icon>
  • <wa-spinner>
  • <wa-tag>
Need a hand? Report a bug Ask for help
Go Make Something Awesome
Version 3.13.0 © Fonticons, Inc.
  • Terms
  • Privacy
  • Refunds
  • Core License
  • Pro License

Quick Links

  • Components
  • CSS Utilities
  • Theming
  • Using with AI
  • Changelog
  • Help & Support

Recent Searches

    D'oh! No results for “”

    Suggest on GitHub Ask on Discord
    Navigate Select
    Close Esc

    We Have Cookies…

    We use cookies to make webawesome.com work better by storing limited information about your usage.

    We value your privacy, so we won't use them for evil or ask you to join the dark side.

    Customize
    Necessary Only Accept All
    Strictly Necessary
    Required to make the site function correctly — cannot be turned off
    Functionality Analytics
    Cancel Confirm Cookie Choices