blade-flags

Laravel | Vue | React | Vanilla JS | Variants | Contributing

1,759 SVG country and language flags for Laravel Blade, Vue, React, and vanilla JavaScript. Three flag styles, 128 language mappings, and full support for regional variants like ar-sa, en-us, and fr-ca. Works great with Inertia.js.

Use them anywhere — locale switchers, address forms, dashboards, or admin panels.

For a full list of available icons see the SVG directories: default, circle, flat.

# Laravel / PHP
composer require outhebox/blade-flags

# Vue
npm install @blade-flags/core @blade-flags/vue

# React
npm install @blade-flags/core @blade-flags/react

# Vanilla JS / Node
npm install @blade-flags/core

Requires PHP 8.0+ and Laravel 9+. Uses Blade Icons under the hood — see their readme for caching and additional features.

Watch a 3-minute video by Povilas Korop showcasing the package.

Icons can be used as self-closing Blade components which will be compiled to SVG icons.

<x-flag-country-us />
<x-flag-country-gb />
<x-flag-country-br />
<x-flag-country-cn />
<x-flag-country-ru />

...produces this:

<x-flag-language-en />
<x-flag-language-ar />
<x-flag-language-es />

...produces this:

<x-flag-circle-country-us />
<x-flag-circle-country-gb />
<x-flag-circle-country-br />
<x-flag-circle-country-cn />
<x-flag-circle-country-ru />

...produces this:

<x-flag-circle-language-en />
<x-flag-circle-language-ar />
<x-flag-circle-language-ar-sa />
<x-flag-circle-language-ar-eg />

...produces this:

<x-flag-flat-country-us />
<x-flag-flat-country-gb />
<x-flag-flat-country-br />
<x-flag-flat-country-cn />
<x-flag-flat-country-ru />

...produces this:

<x-flag-flat-language-en />
<x-flag-flat-language-ar />
<x-flag-flat-language-fr />

...produces this:

You can pass classes to any variant:

<x-flag-country-us class="w-6 h-6"/>
<x-flag-circle-country-us class="w-6 h-6"/>
<x-flag-flat-country-us class="w-6 h-6"/>

For dynamic icon names (e.g. from a database or variable), use the @svg Blade directive:

@svg('flag-country-'.$country->iso2_code)
@svg('flag-circle-country-'.$country->iso2_code, 'w-6 h-6')
@svg('flag-flat-country-'.$country->iso2_code)

@svg('flag-language-'.$language->code)
@svg('flag-circle-language-'.$language->code, 'w-6 h-6')
@svg('flag-flat-language-'.$language->code)

Or the svg() helper in PHP:

svg('flag-country-us')->toHtml()
svg('flag-circle-country-us', 'w-6 h-6')->toHtml()

Publish the raw SVG files as public assets:

php artisan vendor:publish --tag=blade-flags --force
php artisan vendor:publish --tag=blade-flags-circle --force
php artisan vendor:publish --tag=blade-flags-flat --force

Then use them in your views:

<img src="{{ asset('vendor/blade-flags/country-us.svg') }}" width="32" height="32"/>
<img src="{{ asset('vendor/blade-flags-circle/circle-country-us.svg') }}" width="32" height="32"/>
<img src="{{ asset('vendor/blade-flags-flat/flat-country-us.svg') }}" width="32" height="32"/>

Blade Flags also offers the ability to use features from Blade Icons like default classes, default attributes, etc. If you'd like to configure these, publish the blade-flags.php config file:

php artisan vendor:publish --tag=blade-flags-config

By default, language flags use the country mappings defined in config/language-countries.json (e.g. ar → UAE, en → UK). You can override these defaults per-language:

1. Publish the config file:

   php artisan vendor:publish --tag=blade-flags-config

2. Edit config/blade-flags.php to set your preferred mappings:

   'language_overrides' => [
       'ar' => ['default' => 'sa'],  // Arabic → Saudi Arabia
       'en' => ['default' => 'us'],  // English → United States
   ],

3. Publish the SVG assets and apply your overrides:

   php artisan vendor:publish --tag=blade-flags --force
   php artisan vendor:publish --tag=blade-flags-circle --force
   php artisan vendor:publish --tag=blade-flags-flat --force
   php artisan blade-flags:generate

The blade-flags:generate command reads the package defaults, merges your overrides, and regenerates the language flag SVGs in the published vendor directories.

Works with Vue 3.3+. Ideal for Inertia.js apps.

<script setup>
import { Flag } from '@blade-flags/vue'
import { circleFlags } from '@blade-flags/core/flags/circle'
</script>

<template>
  <!-- Dynamic: pass the full map, resolve by code at runtime -->
  <Flag :code="user.country" :flags="circleFlags" />
  <Flag code="ar-sa" type="language" :flags="circleFlags" />
</template>

When the flags are known at build time, pass the SVG directly and only those flags ship:

<script setup>
import { Flag } from '@blade-flags/vue/flag'
import { countryAe, countryUs } from '@blade-flags/core/flags/circle'
</script>

<template>
  <Flag :svg="countryAe" />
  <Flag :svg="countryUs" />
</template>

Works with React 18+.

import { Flag } from '@blade-flags/react'
import { circleFlags } from '@blade-flags/core/flags/circle'

// Dynamic: pass the full map, resolve by code at runtime
<Flag code={user.country} flags={circleFlags} />
<Flag code="ar-sa" type="language" flags={circleFlags} />

When the flags are known at build time, pass the SVG directly and only those flags ship:

import { Flag } from '@blade-flags/react/flag'
import { countryAe, countryUs } from '@blade-flags/core/flags/circle'

<Flag svg={countryAe} />
<Flag svg={countryUs} />

Use @blade-flags/core directly in any JavaScript or TypeScript project:

import { resolveFlag } from '@blade-flags/core'
import { circleFlags } from '@blade-flags/core/flags/circle'

// Dynamic: resolve by code at runtime (loads all flags in the variant)
const svg = resolveFlag(circleFlags, user.country)
document.getElementById('flag').innerHTML = svg

Every flag is a named export. If you know which flags you need at build time, import them directly — your bundler will tree-shake the rest:

// Only the flags you import end up in your bundle
import { countryUs, countryGb, languageAr, languageArSa } from '@blade-flags/core/flags/circle'

Flag names follow the pattern country{Code} and language{Code} in camelCase:

Every flag is also its own module, so a code that comes from data can be loaded on demand without shipping the whole variant:

// One flag, one chunk: bundlers turn this into a lazy chunk per flag
const { svg } = await import(`@blade-flags/core/flags/circle/country-${code}`)

Module paths follow the SVG key: @blade-flags/core/flags/{variant}/{type}-{code}, for example flags/circle/country-ae, flags/flat/language-ar-sa. Each exports a single svg string (ESM only).

For dynamic use where you prefer one import, load the full variant map. The Flag component uses this approach:

// Loads all flags in the variant — use when the code isn't known at build time
import { circleFlags } from '@blade-flags/core/flags/circle'
import { resolveFlag } from '@blade-flags/core'

const countrySvg = resolveFlag(circleFlags, 'us')              // country flag
const languageSvg = resolveFlag(circleFlags, 'ar-sa', 'language') // language flag

Import only the variant you need:

import { defaultFlags } from '@blade-flags/core/flags/default'  // 264 country + 281 language
import { circleFlags } from '@blade-flags/core/flags/circle'    // 405 country + 275 language
import { flatFlags } from '@blade-flags/core/flags/flat'        // 270 country + 264 language

Both component packages are side-effect free and expose three entry points:

The AutoFlag convenience component accepts a variant string prop but bundles all variants:

<script setup>
import { AutoFlag } from '@blade-flags/vue'
</script>

<template>
  <AutoFlag code="us" variant="circle" />
</template>

This package aims for broad compatibility by mirroring upstream flag collections. Inclusion of any flag does not imply endorsement. The author of this package stands with Palestine (the Palestine flag is featured in the project cover). If you want to exclude specific flags, you can do so in your application/UI, or exclude them during the build via bin/build.sh.

Please see CONTRIBUTING for details.

Blade Flags is open-sourced software licensed under the MIT license.