Vue Country Flag Component

2.3.2 · active · verified Tue Apr 21

vue-country-flag is a lightweight Vue 2 component designed for displaying country flags, primarily utilizing ISO 3166-1 alpha-2 or alpha-3 country codes. The package is currently stable at version 2.3.2, with its release cadence focusing on bug fixes, adding new flags, and minor feature enhancements such as `rounded` borders and `shadow` effects. A key differentiator and performance improvement was introduced in v2.1.0, which shifted from embedding flag images as base64 strings in CSS to loading them as separate files, significantly reducing the bundle size by approximately 700KB. Although a patch in v2.0.4 noted it was 'usable on Vue3', its `peerDependencies` explicitly target Vue 2 (`^2.6.12`), indicating its core compatibility. It supports customizable sizes ('small', 'normal', 'big') and is marked as TypeScript supported.

Common errors

```
Failed to resolve component: country-flag
```
cause The `CountryFlag` component has not been correctly registered with Vue.

fix Ensure you have either registered it globally via `Vue.component('country-flag', CountryFlag)` in your `main.js` or locally within the `components` option of your Vue component: `components: { CountryFlag }`.
```
Error: Cannot find module 'vue-country-flag'
```
cause The `vue-country-flag` package is not installed or the import path is incorrect.

fix Run `npm install vue-country-flag` or `yarn add vue-country-flag`. Verify your import statement: `import CountryFlag from 'vue-country-flag'`.
```
[Vue warn]: Invalid prop: type check failed for prop "country". Expected String, got Undefined.
```
cause The `country` prop is mandatory and was either not provided or was provided with an undefined value.

fix Ensure you pass a valid ISO 3166-1 alpha-2 or alpha-3 string to the `country` prop, e.g., `<country-flag country='it' />`.

Warnings

breaking The internal CSS base class for flags was renamed in v2.0.1. Any custom styles or overrides targeting the old class names will cease to work.
Fix: Review your CSS and update selectors to match the new class names. Consult the component's generated HTML for the current class structure.
gotcha In v2.1.0, the component changed its method of loading flag images from base64 encoded strings in CSS to separate image files. While this significantly reduced bundle size (~700KB), it might require adjustments to build configurations or asset serving in specific environments (e.g., if you were previously relying on completely self-contained CSS).
Fix: Ensure your build process and deployment environment are configured to correctly serve static assets. No direct code change is typically needed for standard setups, but be aware of potential issues in highly customized environments.
gotcha Although v2.0.4 mentioned making the component 'usable on Vue3', the package's `peerDependencies` explicitly require Vue 2 (`^2.6.12`). While it might function in some Vue 3 setups, it is not officially supported for Vue 3 and may lead to unexpected behavior or future incompatibilities.
Fix: For production Vue 3 applications, consider using a flag component specifically designed and maintained for Vue 3. Use this package with caution in Vue 3, understanding its primary target is Vue 2.
gotcha The component relies on ISO 3166-1 alpha-2 or alpha-3 codes for country identification. Providing an invalid or non-existent code for the `country` prop will result in a broken image or no flag being displayed.
Fix: Always use valid ISO 3166-1 alpha-2 (e.g., 'us', 'fr') or alpha-3 (e.g., 'usa', 'fra') codes. Refer to the 'Available Flags' section in the documentation for a full list of supported codes.

Install

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

Imports

CountryFlag
wrong:
```
const CountryFlag = require('vue-country-flag')
```
correct:
```
import CountryFlag from 'vue-country-flag'
```
The component is distributed as an ES Module. Use `import` for modern Vue CLI or Vite projects.
Vue.component for global registration
```
import Vue from 'vue'
import CountryFlag from 'vue-country-flag'
Vue.component('country-flag', CountryFlag)
```
Common pattern for making the component available globally across a Vue 2 application.
Local component registration
```
import CountryFlag from 'vue-country-flag';
export default {
  components: { CountryFlag }
}
```
Recommended approach for components used in specific Vue Single File Components (SFCs).

Quickstart

This quickstart demonstrates how to globally register the `CountryFlag` component and use it within a basic Vue 2 application, showcasing different `country`, `size`, `rounded`, and `shadow` prop configurations.

import Vue from 'vue';
import CountryFlag from 'vue-country-flag';

// Register the component globally
Vue.component('country-flag', CountryFlag);

// Example Vue app setup
new Vue({
  el: '#app',
  template: `
    <div id="app">
      <h1>Country Flags</h1>
      <p>Displaying various country flags with different sizes and styles.</p>
      <country-flag country='us' size='big' shadow />
      <country-flag country='fr' size='normal' />
      <country-flag country='de' size='small' rounded />
      <country-flag country='jp' />
      <country-flag country='rus' size='big' />
    </div>
  `
});

view raw JSON →