MazSelectCountry

MazSelectCountry is a versatile Vue component for selecting countries or languages with built-in internationalization support and customizable display options

TIP

This component can be translated globally using the MazUi plugin.

Basic usage

The most common use case is selecting a country. The component automatically displays country names in the user's locale with their respective flags.

Select a country

Selected: FR

<script setup>
import { ref } from 'vue'

const selectedCountry = ref('FR')
</script>

<template>
  <MazSelectCountry
    v-model="selectedCountry"
    label="Select a country"
  />
</template>

Language selection

Configure the component to display languages instead of countries by setting the appropriate displayNamesOptions.

Select a language

Selected: en-US

<script setup>
import { ref } from 'vue'

const selectedLanguage = ref('en')
</script>

<template>
  <MazSelectCountry
    v-model="selectedLanguage"
    label="Select a language"
    :display-names-options="{ type: 'language' }"
  />
</template>

Sizes and colors

Sizes

Small

Medium (default)

Large

Colors

Primary

Secondary

Accent

<template>
  <!-- Sizes -->
  <MazSelectCountry
    v-model="selectedCountry"
    size="sm"
    label="Small"
  />
  <MazSelectCountry
    v-model="selectedCountry"
    size="md"
    label="Medium (default)"
  />
  <MazSelectCountry
    v-model="selectedCountry"
    size="lg"
    label="Large"
  />

  <!-- Colors -->
  <MazSelectCountry
    v-model="selectedCountry"
    color="primary"
    label="Primary"
  />
  <MazSelectCountry
    v-model="selectedCountry"
    color="secondary"
    label="Secondary"
  />
  <MazSelectCountry
    v-model="selectedCountry"
    color="accent"
    label="Accent"
  />
</template>

Preferred countries

You can prioritize certain countries to appear at the top of the list using the preferredCodes prop.

European countries first

<template>
  <MazSelectCountry
    v-model="selectedCountry"
    label="European countries first"
    :preferred-codes="['FR', 'DE', 'IT', 'ES', 'GB']"
  />
</template>

Filtering options

Control which countries are displayed using onlyCodes to show only specific countries, or ignoredCodes to exclude certain ones.

Only European countries

European countries only

Exclude specific countries

All except some countries

<template>
  <!-- Only specific countries -->
  <MazSelectCountry
    v-model="selectedCountry"
    label="European countries only"
    :only-codes="['FR', 'DE', 'IT', 'ES', 'GB', 'NL', 'BE', 'AT', 'CH', 'PT']"
  />

  <!-- Exclude specific countries -->
  <MazSelectCountry
    v-model="selectedCountry"
    label="All except some countries"
    :ignored-codes="['KP', 'SY', 'AF']"
  />
</template>

Custom display options

Configure how country/language names are displayed using the displayNamesOptions prop, which leverages the browser's Intl.DisplayNames API.

Short country names

Short names

Languages with narrow style

Language names (narrow)

<template>
  <!-- Short country names -->
  <MazSelectCountry
    v-model="selectedCountry"
    label="Short names"
    :display-names-options="{ type: 'region', style: 'short' }"
  />

  <!-- Languages with narrow style -->
  <MazSelectCountry
    v-model="selectedLanguage"
    label="Language names (narrow)"
    :display-names-options="{ type: 'language', style: 'narrow' }"
    hide-flags
  />
</template>

Without flags

Hide country flags using the hideFlags prop for a cleaner text-only interface.

Countries without flags

<template>
  <MazSelectCountry
    v-model="selectedCountry"
    label="Countries without flags"
    hide-flags
    placeholder="Text-only country selection"
  />
</template>

Custom locale

Override the default locale to display country/language names in a specific language.

Countries in French

Pays (French)

Countries in Spanish

País (Spanish)

<template>
  <!-- Countries in French -->
  <MazSelectCountry
    v-model="selectedCountry"
    label="Pays (French)"
    locale="fr-FR"
  />

  <!-- Countries in Spanish -->
  <MazSelectCountry
    v-model="selectedCountry"
    label="País (Spanish)"
    locale="es-ES"
  />
</template>

States and validation

The component supports all the standard form states for better user experience.

Valid country selected

Please verify your selection

Please select a valid country

Selection is not available

<template>
  <MazSelectCountry
    v-model="selectedCountry"
    label="Success state"
    success
    hint="Valid country selected"
  />

  <MazSelectCountry
    v-model="selectedCountry"
    label="Warning state"
    warning
    hint="Please verify your selection"
  />

  <MazSelectCountry
    v-model="selectedCountry"
    label="Error state"
    error
    hint="Please select a valid country"
  />

  <MazSelectCountry
    v-model="selectedCountry"
    label="Disabled state"
    disabled
    hint="Selection is not available"
  />
</template>

Custom options

Provide your own list of options instead of using the built-in country/language codes.

Custom regions

<script setup>
import { ref } from 'vue'

const selectedCustom = ref()
const customRegions = [
  { code: 'EUROPE', name: 'Europe' },
  { code: 'ASIA', name: 'Asia' },
  { code: 'AFRICA', name: 'Africa' },
  { code: 'AMERICAS', name: 'Americas' },
  { code: 'OCEANIA', name: 'Oceania' }
]
</script>

<template>
  <MazSelectCountry
    v-model="selectedCustom"
    label="Custom regions"
    :options="customRegions"
    hide-flags
  />
</template>

Display code instead of name

Show country/language codes in the input field instead of names using the displayCode prop.

Display country codes

<template>
  <MazSelectCountry
    v-model="selectedCountry"
    label="Display country codes"
    display-code
    placeholder="Shows codes like 'FR', 'US'..."
  />
</template>

Advanced configuration

Combine multiple features for complex use cases, such as business applications requiring specific country lists with custom styling.

Primary business regions prioritized

<template>
  <MazSelectCountry
    v-model="selectedCountry"
    label="Business countries"
    color="primary"
    size="lg"
    :preferred-codes="['US', 'GB', 'DE', 'FR', 'CA']"
    :ignored-codes="['AQ', 'BV', 'HM']"
    :search-threshold="2"
    display-code
    success
    hint="Primary business regions prioritized"
  />
</template>

How it works

The MazSelectCountry component is built on top of MazSelect and leverages the powerful useDisplayNames composable, which uses the browser's native Intl.DisplayNames API for internationalization.

Key features:

• Automatic localization: Country and language names are displayed in the user's locale
• Built-in search: Users can quickly find countries by typing
• Flag integration: Automatic flag display using country codes
• Flexible filtering: Support for preferred, ignored, or specific country lists
• Custom options: Override default behavior with custom data
• Accessibility: Full keyboard navigation and screen reader support

useDisplayNames composable

The component uses the useDisplayNames composable internally, which provides:

// Get display name for a single code
const displayName = getDisplayName('FR', {
  locale: 'en-US',
  type: 'region'
})

// Get all display names with filtering
const allCountries = getAllDisplayNames({
  locale: 'en-US',
  codesType: 'country',
  preferred: ['US', 'GB', 'FR'],
  exclude: ['AQ']
})

This ensures consistent internationalization across your application while providing maximum flexibility for different use cases.

Props

Name	Description	Type	Required	Default	Possible values
style	Style attribut of the component root element	HTMLAttributes['style']	No	undefined	-
class	Class attribut of the component root element	HTMLAttributes['class']	No	undefined	-
id	Id of the component	string	No	undefined	-
color	Color of the component	MazColor	No	primary	-
size	Size of the component	MazSize	No	md	-
preferred-codes	Preferred countries to display	Option['code'][]	No	undefined	-
ignored-codes	Ignored countries to display	Option['code'][]	No	undefined	-
only-codes	Only countries to display	Option['code'][]	No	undefined	-
list-position	Position of the list	MazPopoverProps['position']	No	auto	-
hide-flags	Hide flags	boolean	No	undefined	-
search	Display search input in options list	boolean	No	true	-
show-code-in-list	Show code on list	boolean	No	false	-
locale	Locale	string	No	locale defined within the maz-ui plugin or browser locale or en-US	-
success	Success state	boolean	No	undefined	-
error	Error state	boolean	No	undefined	-
warning	Warning state	boolean	No	undefined	-
display-code		boolean	No	undefined	-
search-threshold	Search threshold	number	No	undefined	-
translations	Translations	Partial<MazUiTranslationsNestedSchema['selectCountry']>	No	MazUiTranslationsNestedSchema['selectCountry']	-
hint	Hint message displayed	string	No	undefined	-
options	Options	Option[]	No	undefined	-
display-names-options	Display name type	Intl.DisplayNamesOptions	No	{ type: 'region', languageDisplay: 'standard', fallback: 'code', style: 'long' }	-
codes-type	Codes type	CodesType	No	defined by displayNamesOptions.type (if 'region', 'country' is used, otherwise 'iso')	iso' | 'bcp' | 'country' | 'all
open	Open the select	boolean	No	false	-

Events

Event name	Properties	Description
update:model-value	value Option['code'] | undefined - The new value	Emitted when the model value changes

Slots

Name	Description	Bindings
selector-flag	Country selector flag	country-code String - current selected country code - Ex: "FR"
no-results
country-list-flag	Country list flag	option { code: string; name: string; } - country data is-selected Boolean - true if option is selected
country-list-code
country-list-name