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>

Flags source

By default, the flags are images of the flagcdn.com CDN: each user's browser requests them from this third party. The flag-src prop changes where they come from, in four ways:

Source	flag-src	Network
CDN (default)	not set	flagcdn.com
Flags of maz-ui	loadCountryFlag from maz-ui/country-flags	none (works offline)
Your own files	URL template: '/flags/{code}.svg'	your server
Your own function	(code) => string | undefined | Promise<string | undefined>	yours

In every case, a flag is only loaded when it becomes visible (the selected country, then the rows of the open list in view), and a code without flag displays the colored badge.

For the whole app

Set it once instead of on every component: the flag-src of MazSelectCountry and MazInputPhoneNumber both default to defaults.global.flagSrc (see Global component defaults). A flag-src set on a component always wins.

// Vue: main.ts
import { loadCountryFlag } from 'maz-ui/country-flags'
import { MazUi } from 'maz-ui/plugins/maz-ui'

app.use(MazUi, {
  theme: { preset: mazUi },
  defaults: {
    global: { flagSrc: loadCountryFlag }, // or a URL template: '/flags/{code}.svg'
  },
})

// Nuxt: nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@maz-ui/nuxt'],
  mazUi: {
    flags: 'local', // 'cdn' (default) | 'local' | a URL template: '/flags/{code}.svg'
  },
})

Flags of maz-ui, offline

loadCountryFlag gives the square flag of a code from the 256 flags of @maz-ui/icons, as a data:image/svg+xml URL: no request to a third party (nothing to allow for flagcdn.com in your Content Security Policy, the user's IP is not sent to it), and the component works offline (hybrid apps with Capacitor or Cordova, PWAs, intranets).

Country (flags of maz-ui)

<script lang="ts" setup>
import { loadCountryFlag } from 'maz-ui/country-flags'
import { ref } from 'vue'

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

<template>
  <MazSelectCountry
    v-model="selectedCountry"
    label="Country (flags of maz-ui)"
    :flag-src="loadCountryFlag"
  />
</template>

How it stays light:

• Nothing in maz-ui imports maz-ui/country-flags: an app that does not import it has no flag file at all in its build.
• Once imported, your bundler emits one small chunk per flag (256 files, from a few hundred bytes to a few kilobytes each). None is preloaded: only the flags displayed are downloaded.
• The loader itself (a table of 256 dynamic imports, about 4 kB gzipped) goes into the chunk that imports it. To keep it out of your entry chunk, import it on demand (the Nuxt option flags: 'local' does it for you):

const flagSrc = (code: string) => import('maz-ui/country-flags').then(({ loadCountryFlag }) => loadCountryFlag(code))

Content Security Policy

The flags are data: URLs: a strict CSP must allow img-src data: (already needed by the lazy images of maz-ui).

PWA precache

Once you use loadCountryFlag, the 256 flag chunks are part of your build, so a service worker that precaches every **/*.js downloads all of them at install. Keep them (every flag available offline) or exclude them and let them load on demand. With Vite, the chunks are named after their module, MazFlagSquareFR-[hash].js:

// vite-plugin-pwa
VitePWA({ workbox: { globIgnores: ['**/MazFlagSquare*.js'] } })

Nuxt names its chunks _nuxt/[hash].js only: name the flag chunks yourself to exclude them, e.g. vite.build.rollupOptions.output.chunkFileNames: chunk => chunk.name.startsWith('MazFlagSquare') ? '_nuxt/flags/[name].[hash].js' : '_nuxt/[hash].js', then ignore **/_nuxt/flags/**.

Your own files

A URL template, with {code} for the lowercase code and {CODE} for the uppercase code. The images are lazy loaded like the CDN ones. A missing image displays the badge.

<template>
  <!-- public/flags/fr.svg, public/flags/de.svg... -->
  <MazSelectCountry v-model="selectedCountry" flag-src="/flags/{code}.svg" />

  <!-- another host, uppercase codes -->
  <MazSelectCountry v-model="selectedCountry" flag-src="https://assets.example.com/flags/{CODE}.png" />
</template>

Your own function

A function receives the country code of each flag when it becomes visible, and returns the image source (URL or data URL), or undefined to display the badge. It can be async: only the flags displayed are loaded.

<script lang="ts" setup>
// One file per flag in your project, loaded on demand (Vite turns this import into one chunk per file)
function flagSrc(code: string) {
  return import(`./assets/flags/${code.toLowerCase()}.svg?url`)
    .then(module => module.default)
    .catch(() => undefined)
}
</script>

<template>
  <MazSelectCountry v-model="selectedCountry" :flag-src="flagSrc" />
</template>

You can also replace the flags entirely with the selector-flag and country-list-flag slots.

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, from the flagcdn.com CDN, the flags of maz-ui (offline) or your own files
• 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
id	Id of the component	string	No	-	-
color	Color of the component	"primary" | "secondary" | "accent" | "info" | "success" | "warning" | "destructive" | "contrast" | "transparent"	No	"primary"	'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'destructive' | 'contrast' | 'transparent'
size	Size of the component	"xs" | "sm" | "md" | "lg" | "xl" | "mini"	No	md	'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'mini'
preferred-codes	Preferred countries to display	Option["code"][]	No	-	-
ignored-codes	Ignored countries to display	Option["code"][]	No	-	-
only-codes	Only countries to display	Option["code"][]	No	-	-
list-position	Position of the list	MazPopoverPosition	No	'auto'	-
hide-flags	Hide flags	boolean	No	-	-
flag-src	Source of the flags, instead of the flagcdn.com CDN: - a URL template with the code, {code} (lowercase) or {CODE} (uppercase): /flags/{code}.svg - a function giving the image source of a code (URL or data URL), called when the flag becomes visible, or undefined to display the code in a badge Use loadCountryFlag from maz-ui/country-flags for the flags of @maz-ui/icons, without any request to a third party. Can be set for the whole app with the defaults.global.flagSrc option of the MazUi plugin.	MazCountryFlagSrc	No	undefined (flags from flagcdn.com)	-
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	-	-
error	Error state	boolean	No	-	-
warning	Warning state	boolean	No	-	-
display-code		boolean	No	-	-
search-threshold	Search threshold	number	No	0.75	-
translations	Translations	Partial<{ searchPlaceholder: string; }>	No	MazUiTranslationsNestedSchema['selectCountry']	-
hint	Hint message displayed	string	No	-	-
options	Options	Option[]	No	-	-
display-names-options	Display name type	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	-
model-value	v-model The value of the select	Option["code"]	No	-	-
block	The input will be displayed in full width	boolean	No	-	-
disabled	Disable the component	boolean	No	-	-
required	Make the input required in the form	boolean	No	-	-
placeholder	The placeholder of the select	string	No	-	-
label	The label of the select	string	No	-	-
search-function	Replace the default search function to provide a custom search function	((query: string, options: Option[]) => Option[] | undefined)	No	-	-
transition	The transition name of the panel list options	string	No	'scale-fade'	-
prefer-position	The prefer position of the list	MazPopoverPreferPosition	No	'bottom-start'	-
fallback-position	The fallback position of the list	MazPopoverFallbackPosition	No	'top-start'	-
top-label	Static label displayed above the input field. Unlike the floating label, this remains fixed	string	No	-	-
autocomplete	The autocomplete attribute of the input	string	No	'off'	-
option-value-key	The key of the option value	string	No	"code"	-
option-label-key	The key of the option label	string	No	"name"	-
option-input-value-key	The key of the option input value	string	No	"name"	-
item-height	The height of the option list item	number	No	-	-
max-list-height	The max height of the option list	number	No	240	-
max-list-width	The max width of the option list	number	No	250	-
min-list-height	The min height of the option list	number	No	-	-
min-list-width	The min width of the option list	number	No	200	-
format-input-value	The function to format the input value	((value: Option["code"]) => string)	No	-	-

Events

Event name	Payload	Description
update:model-value	value?: Option["code"] | undefined	Emitted when the model value changes

Slots

Name	Description	Bindings
selector-flag	Country selector flag	countryCode Option["code"] - current selected country code - Ex: "FR"
no-results		-
country-list-flag	Country list flag	option Option - country data isSelected boolean - true if option is selected
country-list-code		option Option isSelected boolean
country-list-name		option Option isSelected boolean