Laravel Country Flags Laravel Package

Getting Started

stidges/laravel-country-flags wraps an ISO 3166-1 alpha-2 flag sprite as a Blade component + helper, so you don't hand-roll <svg> markup or ship 250+ individual icon files.

Minimal path:

1. Install:

   composer require stidges/laravel-country-flags
   

2. Publish the config (optional, but do it early — it holds the defaults):

   php artisan vendor:publish --tag="country-flags-config"
   

3. Render your first flag in a Blade view:

   <x-country-flag country="us" />
   

   or via the helper:

   {!! country_flag('us') !!}
   

First real use case: a locale switcher or a shipping-address form. Store the ISO 3166-1 alpha-2 code (e.g. US, nl) in the DB and pass it at render time:

@foreach ($locales as $locale)
    <x-country-flag :country="$locale->country_code" class="w-5 h-4 inline-block" />
    {{ $locale->name }}
@endforeach

Where to look first:

• config/country-flags.php — default CSS classes, sprite/symbol prefix, default attributes.
• The service provider — registers the Blade component and helper and wires up the underlying sprite package.
• vendor/stidges/laravel-country-flags/resources/views — the actual component template if you need to override markup.

Release note (v3.0.1): this is explicitly Laravel 12.x compatibility. On Laravel 12, pin ^3.0.1; earlier 3.x will fail dependency resolution against the framework.

Implementation Patterns

Component vs. helper. Use <x-country-flag> in static templates (self-documenting, IDE-friendly). Use the country_flag() helper when the code comes from runtime data — loops, policies, mailables, JSON-LD.

Model accessor for flags. Keep codes in the DB, render in the view:

public function getFlagAttribute(): HtmlString
{
    return country_flag($this->country_code);
}

Sprite-based rendering. The package references a shared SVG sprite rather than inlining a full flag per item — ideal for grids of 50+ countries, where the browser reuses the same symbols.

Pair with a country list. For select menus, source code and label from the same place (stidges/country-flags' list or symfony/intl) so flags and names can't drift.

Validation. Gate input with Rule::in(array_keys(config('countries'))) or a backed enum of country codes. The flag component is presentation, not validation.

Mailable / notification usage. The helper returns markup; pass it into the mail payload and render it with {!! !!} in the email template rather than echoing in PHP.

Sizing and Tailwind. Pass size utilities per instance (class="w-6 h-4") and keep a 3:2 default so rows align. The component accepts pass-through attributes, so most styling needs no view override.

Testing. Blade::render() the component and assertSeeHtml the expected symbol/attribute. Don't snapshot the whole SVG — sprite IDs can change across releases.

Gotchas and Tips

Invalid or missing codes. Input must be a valid ISO 3166-1 alpha-2 code. Casing is normalized, but XX/null won't map to a symbol and will render an empty <svg>. Validate and fall back to a known placeholder flag if you need a "no country" state.

The sprite must be on the page. The component emits <use href="#...">. If the sprite isn't loaded — include it once in your layout, typically before </body> — you get blank rectangles. This is the most common "the package is broken" report.

Escaping. The helper returns HtmlString; in Blade use {!! !!}. In Livewire string properties, raw PHP concatenation, or a JSON payload, you'll get escaped markup — keep rendering in the view.

Content-Security-Policy. Inline <use> and inline style attributes may be blocked under a strict CSP. Self-host the sprite, adjust img-src/style-src (or use nonces), and prefer class-based styling.

Config cache. The published config drives defaults (class, prefix, attributes). With php artisan config:cache in production, deploy the config change before caching; hot edits to config/country-flags.php won't take effect otherwise.

Version / compatibility. This is the ^3 line; v3.0.1 adds Laravel 12 support. Check composer.json / CI matrix before bumping from v2 or before downgrading Laravel/PHP — the 3.x branch may have dropped older framework versions. Pin exact and test on a branch.

Override surface. To change markup, publish views (--tag=country-flags-views) and edit under resources/views/vendor/country-flags; keep the override small so upgrade diffs stay readable.

Performance. One sprite request reused across the page — cheap per <use>. Don't render thousands of flags in one response without pagination; cache the rendered grid (Cache::remember) when the country set is static.