Aqua Basis

The AqFlagSelector component is a form control that allows users to select a country using flags as visual identifiers. It supports multiple display modes, including showing only the country name, call sign, or the full name, depending on the configuration.

<aq-flag-selector 
		id="flag-selector-1"
		label="Flag Selector"
		info="This is a tooltip"
		is-required="true"
		is-disabled="false"
		is-readonly="false"
		is-outline="false"
		is-error="false"
		is-name="true"
		show-call-sing="true"
		show-short-name="false"
		identifier="iso2"
		helper-text="This is a helper text"
		noResultsText = "No results found"
		placeholder="This is a placeholder"
		isSelect="false"
		clean-on-escape="false"
		close-on-select="false"
		countryDefault=""
		></aq-flag-selector>

<script>
  const flagSelector = document.querySelectorAll('aq-flag-selector');
   flagSelector.forEach(flag => {
    flag.countries = countries = ["57",
      "503", // El Salvador
      "91", // India 
      "56", // Chile
      "32", // Belgium
      "52", // Mexico
      "51", // Peru
      "507", // Panama
      "54", // Argentina
      "65", // Singapore
      "1-787", // Puerto Rico
      "1-809", // Dominican Republic
      "1-829", // Dominican Republic
      "1-849", // Dominican Republic
      "1-868", // Trinidad and Tobago
      "1-869", // Saint Kitts and Nevis
      "1-876", // Jamaica
      "297", // Aruba
      ]
    })
</script>

Developers can customize its behavior with options such as:

Validation states (isRequired, isError, isDisabled, isReadonly).
Styling (isOutline, popoverWidth).
Display modes (isFullName, isName, isCallSign).
Behavioral controls (cleanOnEscape, cleanOnSelect).

It supports both static country lists (via the countries property) and value transformation (getCountries → iso2, iso3, or full country name). Additionally, it provides helper texts, placeholders, and "no results" messages for enhanced UX.

This component is ideal for applications requiring internationalization features or country-based form inputs (e.g., phone number selection, nationality pickers).

Props and Attributes

Core props

Prop / Attribute	Type	Default	Description
`popoverWidth`	`POPOVER_WIDTHS`	`AUTO`	Width of the autocomplete popover.
`value`	`string`	`''`	Current value. Updated according to `getCountries`.
`label`	`string`	`''`	Visible field label.
`info`	`string`	`''`	Informative text/tooltip for the field.
`isRequired`	`boolean`	`false`	Mark the field as required.
`isDisabled`	`boolean`	`false`	Disable the field.
`isReadonly`	`boolean`	`false`	Read-only.
`isOutline`	`boolean`	`false`	Alternative style (outline).
`isError`	`boolean`	`false`	Show error status.
`isName`	`boolean`	`true`	Show/use the country name in the items.
`showCallSign`	`boolean`	`false`	Show the telephone code (country/calling code).
`showShortName`	`boolean`	`false`	Show short name if applicable.
`identifier`	`'iso2'	'iso3'	'country'`
`helperText`	`string`	`''`	Help text below the field.
`noResultsText`	`string`	`'No results found'`	Text when there are no search results. (Be sure to pass it to aq-`aq-autocomplete` if you need it)
`placeholder`	`string`	`''`	Input placeholder.
`isSelect`	`boolean`	`false`	Change autocomplete mode to button (select type).
`cleanOnEscape`	`boolean`	`false`	Clear the value when Escape is pressed.
`closeOnSelect`	`boolean`	`false`	Close the popover when an option is selected.
`countryDefault`	`string`	`""`	Default country. Can be country (telephone code), iso2, or iso3 (see Values and normalization).
`countries`	`Array<string	number>`	`[]`
`getCountries`	`'country'	'iso2'	'iso3'`

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-aqflagselector--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>

Binding Support by Framework

Framework	Two-Way Binding Support	Example	Notes
Vue 3	✅ `v-model`	`v-model="valueFlagSelector"`	Works with `ref` binding and emits updates
Angular	✅ `[(ngModel)]`	`[(ngModel)]="valueFlagSelector”`	Requires FormsModule or standalone setup
React	⚠️ Manual
Web Components	⚠️ Manual

Special Notes

⚠️ Note: List of available countries in this link https://flagicons.lipis.dev/