Aqua Basis

The AqAutocomplete component allows users to select one or multiple options with optional search capability. It supports single and multiple selection, input mode for typing to filter options, and button mode to open a popover without search, emulating a select behavior.

<aq-autocomplete
  label="This is a label"
  placeholder="Search something..."
  helper-text="This is a helper text"
  icon="aq-icon-send"
  sublabel="Sub"
  popover-width="auto"
  no-results-text="No results found"
  type-autocomplete="input"
  font-size-selected-option="1rem"
>
  <div slot="header">
    <aq-button>header slot button</aq-button>
  </div>
  <div slot="footer">
    <aq-button>footer slot button</aq-button>
  </div>
</aq-autocomplete>

Props and Attributes

Core props

Control the behavior, style, and base data of aq-autocomplete. They include labels, states (is-disabled, is-error), popover configuration, display mode (input or button), and return values.

They are relevant in both single and multiple selection modes, as they determine how the component is displayed and how users interact with the autocomplete field in its core usage.

Prop / Attribute	Type	Default	Description
`autocomplete`	`'off'	'on'`	`'off'`
`autocompleteType`	`'button'	'input'`	`'input'`
`cleanOnEscape`	`boolean`	`false`	Clears the selected value and active search filter when pressing Escape.
`closeOnSelect`	`boolean`	`false`	Closes the popover when an option is selected or deselected (supports single and multiple selection).
`disabledAllOptions`	`boolean`	`false`	Disables all selectable options in the list.
`fontSizeSelectedOption`	`string`	`'0.875rem'`	Sets the font size for the placeholder (single and multiple modes) and for the selected option (single mode). Accepts units like `px`, `rem`.
`helperText`	`string`	`''`	Helper text displayed below the field.
`icon`	`string`	`''`	Displays an icon inside the input, aligned to the left of the sublabel.
`idParent`	`string`	`''`	Specifies the ID of the reference to the parent container or activator.
`info`	`string`	`''`	Sets the tooltip text that appears while hovering the label info icon.
`isDisabled`	`boolean`	`false`	Disables user interaction while keeping the placeholder or selected value visible with reduced opacity.
`isError`	`boolean`	`false`	Applies error styling with the danger primary base color to the outline and helper text while allowing normal interaction.
`isLoading`	`boolean`	`false`	Displays a loading spinner inside the field and blocks user interaction while active.
`isPlain`	`boolean`	`false`	Removes the outline while maintaining it on hover, error, or disabled states.
`isReadonly`	`boolean`	`false`	Enables readonly mode, showing the selected value or placeholder without allowing modification or popover opening (in button mode).
`isRequired`	`boolean`	`false`	Displays a red asterisk next to the label to indicate the field is required (visual only).
`items`	`any[]`	`[]`	List of selectable options. Each item may include `value`, `text`, `disabled`, `isDivider`, and nested `options` for grouped selections. In multiple mode, `tagConfig` allows customizing selected tags with `tagWidth`, `tagIcon`, and `tagColor`.
`label`	`string`	`''`	Main label displayed above the field.
`noResultsText`	`string`	`'No results'`	Text displayed inside the popover when no matches are found or when the list is empty.
`placeholder`	`string`	`''`	Placeholder text displayed in the field when empty.
`popoverWidth`	`'auto'	'full'	number`
`returnMode`	`'originalObject'	'keys'`	`'originalObject'`
`selectDefault`	`boolean`	`false`	Automatically selects the first available option by default.
`showRadio`	`boolean`	`false`	Displays radio buttons for single selection mode.
`sublabel`	`string`	`''`	Displays secondary text inside the input, aligned to the left.
`tooltipWidth`	`string`	`''`	Sets the width for the tooltip associated with the component label info icon.

Multiple Selection Props

Enable and control the multiple selection mode of AqAutocomplete, allowing users to select multiple options and manage how selections are displayed, counted, and filtered.

💡 Only apply when isMultiple is enabled.

Prop / Attribute	Type	Default	Description
`isMultiple`	`boolean`	`false`	Enables multiple selection mode, allowing users to select multiple options from the popover.

Selected options are displayed as tags inside the field. Does not display checkboxes by default. | | maxShowSelected | number | 2 | Limits the number of visible selected options displayed as tags inside the field in multiple selection mode.

Additional selected options are collapsed into an overflow counter (e.g., +3). Does not affect the popover. | | maxSelect | number | 2 | Sets the maximum number of options a user can select in multiple selection mode.

Once the limit is reached, further selections are blocked in the popover, and the infoBanner (if configured) is displayed. | | cleanFilterOnSelect | boolean | false | Clears the search input and resets the internal filter in the popover when an option is selected.

Used exclusively in multiple selection mode. | | showSelectedCounter | boolean | false | Displays a counter below the field, aligned to the right, showing the number of selected options versus the maximum allowed (e.g., 0/4). Updates in real time.

The select action respects the maxSelect limit. Used exclusively in multiple selection mode. | | showCheckbox | boolean | false | Displays a checkbox to the left of each option within the popover in multiple selection mode, allowing users to select or deselect options directly by interacting with the checkboxes. | | infoBanner | { title: string; message: string; state: string; visible: boolean; close: boolean; } | { title: 'This is a title', message: 'This is a message', state: 'warning', visible: true, close: true } | Displays an information banner at the top of the popover in multiple selection mode.

The banner shows a title, a message, a status (e.g., info, warning), and controls its visibility, typically used to display selection limits or guidance. |

PlayGround

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

<aside> ⚠️

</aside>

Events

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

Event Types

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

Binding Support by Framework

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