Aqua Basis

The AqTagField component allows users to choose, filter, or add multiple options. It is used in forms for users to submit data.

<aq-tag-field
  label="This is a label"
  info="This is a tooltip"
  icon="aq-icon-settings"
  placeholder="Your placeholder goes here"
  is-required
  has-clear
  show-selected-counter
>
</aq-tag-field>

Props and Attributes

Prop / Attr	Type	Default	Description
`idTextField`	`string`	–	ID attribute for the tag field.
`name`	`string`	–	Name attribute for the tag field (used in forms).
`autocomplete`	`string`	`'off'`	Defines the browser’s autocomplete behavior.
`placeholder`	`string`	`''`	Placeholder text displayed when the field is empty.
`maxLength`	`number`	`DEFAULT_MAX_LENGTH`	Maximum allowed characters.
`strictLength`	`boolean`	`false`	Enforces exact character length.
`icon`	`string`	`''`	Custom icon displayed inside the field.
`label`	`string`	`''`	Main label displayed for the field.
`subLabel`	`string`	`''`	Secondary label or helper title.
`info`	`string`	`''`	Info text for tooltip or description.
`tooltipWidth`	`string`	`''`	Defines a custom tooltip width.
`helperText`	`string`	`''`	Supporting text shown below the field.
`isRequired`	`boolean`	`false`	Marks the field as required.
`isError`	`boolean`	`false`	Marks the field as invalid or in an error state.
`isDisabled`	`boolean`	`false`	Disables the field.
`isReadonly`	`boolean`	`false`	Makes the field read-only.
`isPlain`	`boolean`	`false`	Removes borders and styling for a plain look.
`hasClear`	`boolean`	`false`	Displays a clear icon, `ICON_CLOSE`, inside the field.
`addOnKey`	`"Enter"	"Spacebar"`	`"Enter"`
`clearOnEscape`	`boolean`	`false`	Clears the input and all tags when the Escape key is pressed.
`maxSelect`	`number`	`5`	Maximum number of tags that can be selected.
`showSelectedCounter`	`boolean`	`true`	Shows a counter indicating how many tags are currently selected.
`maxShowSelected`	`number`	`3`	Maximum number of tags displayed before moving extra tags into overflow.
`overflowText`	`string`	`"+"`	Text or symbol shown on the overflow counter tag.

PlayGround

You can interact with the component and experiment with its attributes and properties directly in this playground.

In the Code tab, the generated code snippet is available.

In addition to the interactive examples in this documentation, you can explore the full playground with all supported options and advanced configurations at the following link:

👉 Open full playground

https://aqua-ds-playground.masivianlabs.com/doc-storybook/index.html?path=/story/components-forms-aqtagfield--default&nav=0

<aside> ⚠️

Important: The code shown is in Web Component format. If you are using a specific framework (Vue, React, Angular), you must adapt it to the framework’s conventions before using it.

</aside>

Events

Event	Description	React	Angular	Vue	Vanilla JS
`input`	Emitted when the selected tags array changes. Returns `{ value: string[] }`.	`onInput={handleInput}`	`(input)="handleInput($event)"`	`@input="handleInput"`	`addEventListener('input', handler)`
`change`	Emitted when the selected tags array changes (functionally similar to `input`). Returns `{ value: string[] }`.	`onChange={handleChange}`	`(change)="handleChange($event)"`	`@change="handleChange"`	`addEventListener('change', handler)`
`textChange`	Emitted when the user types into the input (before it becomes a tag). Returns `{ value: string }`.	`onTextChange={handleTextChange}`	`(textChange)="handleTextChange($event)"`	`@textChange="handleTextChange"`	`addEventListener('textChange', handler)`
`closeTag`	Emitted when a tag is closed/removed. Returns `{ value: string, idx: number }`, where `value` is the tag content and `idx` is its index in the array.	`onCloseTag={handleCloseTag}`	`(closeTag)="handleCloseTag($event)"`	`@closeTag="handleCloseTag"`	`addEventListener('closeTag', handler)`

Event Types

| --- | --- | --- | --- |

Slots

| --- | --- |

<aq-tag-field
  label="This is a label"
  info="This is a tooltip"
  icon="aq-icon-settings"
  is-required
  placeholder="Your placeholder goes here"
  is-plain
  has-clear
>
  <div slot="left-content">
    <aq-helper-text>left-contents</aq-helper-text>
  </div>
</aq-tag-field>;

Binding Support by Framework

| --- | --- | --- | --- |

In Frameworks

Web Components

<aq-tag-field
  id="aq-tag-field-1"
  label="This is a label"
  info="This is a tooltip"
  icon="aq-icon-settings"
  is-required
  placeholder="Your placeholder goes here"
  has-clear
  clear-on-escape
>
</aq-tag-field>

<script>
  const aqTagField1 = document.getElementById('aq-tag-field-1');
  aqTagField1.addEventListener('change', (e) => {
    console.log('aq-tag-field change: ', e)
  })
  aqTagField1.addEventListener('input', (e) => {
    console.log('aq-tag-field input: ', e)
  })
  aqTagField1.addEventListener('textChange', (e) => {
    console.log('aq-tag-field textChange: ', e)
  })
  aqTagField1.addEventListener('closeTag', (e) => {
    console.log('aq-tag-field closeTag: ', e)
  })
  aqTagField1.validator = (val) => {
    console.log('aq-tag-field validator param: ', val);
    return val.includes('123');
  }
</script>