Vue Country Flag Component

2.3.2 · active · verified Tue Apr 21

vue-country-flag-next is a dedicated Vue 3 component designed for displaying country flags, primarily identified by ISO 3166-1 alpha-2 or alpha-3 codes. The current stable version is 2.3.2, with an active release cadence addressing bug fixes and minor improvements. A key differentiator is its optimized footprint, achieved in v2.1.0 by loading flag images as separate files rather than base64 encoded strings within the CSS, reducing the package size by approximately 700kb. It natively supports TypeScript and integrates seamlessly into Vue 3 projects, offering optional properties for size, rounded borders, and shadows.

Common errors

```
Failed to resolve component: country-flag
```
cause The `CountryFlag` component has not been correctly registered globally or locally within the Vue application.

fix Ensure you have either registered the component globally using `app.component('country-flag', CountryFlag)` (for `main.js`) or locally within a component's `components` option: `components: { CountryFlag }`.
```
TypeError: Cannot read properties of undefined (reading 'install')
```
cause This error can occur if you try to use `CountryFlag` as a Vue plugin (e.g., `app.use(CountryFlag)`), but it is a component, not a plugin with an `install` method.

fix Import `CountryFlag` as a component and register it either globally with `app.component()` or locally within another component's `components` option, instead of trying to use `app.use()`.

Warnings

breaking Prior to v2.1.0, flag images were encoded as Base64 strings directly in the component's CSS. From v2.1.0 onwards, images are loaded as separate files, significantly reducing package footprint but potentially requiring server configuration to serve these assets correctly.
Fix: Ensure your build process and deployment environment are configured to properly serve static assets (e.g., images) from the `node_modules/vue-country-flag-next` directory if you are hosting assets yourself, or ensure your bundler handles it correctly.
breaking In v2.0.0, the `.vue` file was removed from the final npm bundle. This change primarily affects consumers who might have been directly importing or processing the `.vue` single-file component source.
Fix: Ensure you are importing the component via its main entry point (e.g., `import CountryFlag from 'vue-country-flag-next'`) rather than attempting to directly reference the `.vue` file.
gotcha Early versions (prior to v2.0.1) had an issue where the Andorra flag might not be visible due to interactions with AdBlock software, likely due to CSS class names or image URLs resembling ad patterns.
Fix: Update to version 2.0.1 or newer to resolve the AdBlock visibility issue for the Andorra flag and other potential CSS-related conflicts.
gotcha The component requires Vue 3.x as a peer dependency. Attempting to use it with Vue 2.x will result in compatibility errors due to breaking changes in Vue's API between major versions.
Fix: Ensure your project explicitly depends on Vue 3 (`"vue": "^3.0.0"`) in your `package.json` and that your application is built using Vue 3.

Install

npm install vue-country-flag-next npm
yarn add vue-country-flag-next yarn
pnpm add vue-country-flag-next pnpm

Imports

CountryFlag
wrong:
```
const CountryFlag = require('vue-country-flag-next');
```
correct:
```
import CountryFlag from 'vue-country-flag-next';
```
This is the default export for the component. While global registration is shown in the quickstart, local component registration is also a common pattern in modern Vue apps.
App.component
wrong:
```
import { CountryFlag } from 'vue-country-flag-next';
```
correct:
```
import CountryFlag from 'vue-country-flag-next';
app.component('country-flag', CountryFlag);
```
When globally registering the component, you import the default export and then use `app.component` (or `new Vue({ components: ... })` for options API). It's not a named export for direct component registration.

Quickstart

Demonstrates installation via npm, global registration of the `CountryFlag` component in a Vue 3 application, and basic usage within a template with various `country`, `size`, `rounded`, and `shadow` props.

npm install vue-country-flag-next

// main.js or similar entry file
import { createApp } from 'vue';
import App from './App.vue';
import CountryFlag from 'vue-country-flag-next';

const app = createApp(App);

// Register globally for easy use across your application
app.component('country-flag', CountryFlag);

app.mount('#app');

// In a Vue component's template (e.g., App.vue):
// <template>
//   <div>
//     <country-flag country='it' size='big'/>
//     <country-flag country='hr' size='normal'/>
//     <country-flag country='fr' size='small'/>
//     <country-flag country='rus'/>
//     <country-flag country='de' rounded/>
//     <country-flag country='jp' shadow/>
//   </div>
// </template>

view raw JSON →