Laravel Country Flags Laravel Package

Product Decisions This Supports

• Localization & internationalization roadmap: country flag rendering (registration forms, address books, shipping/billing selectors, language or region pickers, store/currency switchers) is a recurring UI need. This package turns that from a bespoke asset-pipeline task into a one-line Blade/helper call, so it directly de-risks any i18n or geo-aware feature on the roadmap.
• Build vs. buy: it is a thin wrapper around a maintained flag asset set. The "build" alternative is sourcing SVGs, naming them consistently, wiring a lookup to ISO 3166-1 alpha-2 codes, and maintaining that mapping forever. Buying (adopting) is the correct default for anything below "flags are a core differentiator for us."
• Design-system consistency: flags in a dropdown are exactly the kind of thing that drifts — inconsistent sizes, aspect ratios, and formats across teams. Centralizing through the package gives a single, versioned source of truth that design can sign off on once.
• Scope control on geo features: if the only geo requirement is "show a flag next to a country name," this closes the ticket. If the requirement grows into country metadata (dial codes, currencies, timezones, tax rules, sanctions lists), that is a separate, heavier data dependency — and a signal to evaluate a broader country-data package rather than extending this one.
• Frontend/backend ownership: it keeps flag rendering in the Blade layer, avoiding a JS-only flag library and a second asset dependency for teams that server-render. Relevant when deciding whether the country selector lives in Livewire/Blade or in a SPA.
• Laravel 12.x compatibility (v3.0.1): the upgrade path is now clear. This removes "framework upgrade is blocked by a leaf UI dependency" from the Laravel 12 migration risk list, which unblocks the broader upgrade decision rather than being a decision in itself.

When to Consider This Package

Adopt it when:

• You are on a supported Laravel version (v3.x line; v3.0.1 explicitly covers Laravel 12.x) and render views server-side with Blade, Livewire, or Inertia.
• Your need is presentational only — displaying a flag glyph for a known ISO country code in a form, table, list, or dropdown.
• You want zero build-step cost: no npm package, no sprite-sheet maintenance, no CDN dependency at runtime.
• You have an existing or upcoming i18n/geo-selector feature and want the flag layer solved in an afternoon rather than a sprint.
• You value a small, single-purpose dependency over a general-purpose "country data" framework.

Look elsewhere when:

• The flag set's visual style or coverage does not match your design language, or you need non-country flags (regions, subdivisions, organizations, historical states) — the package is country-scoped.
• You need the flag itself to be data (colors, SVG paths for theming, custom artwork) rather than prebuilt output.
• You require country metadata: calling codes, currencies, subdivisions, VAT/tax logic, address formats, or geo-IP resolution. This package will not get you there, and stretching it is a sign you want a broader country-data library plus a geo service.
• You are on an unsupported Laravel/PHP combination, or your app is API-only with no server-rendered UI layer — the value proposition largely disappears.
• You have a hard policy against small single-maintainer dependencies for user-facing surfaces. That is a legitimate position; the mitigation is to vendor the assets or keep a one-file fallback renderer.
• Accessibility and semantics are strict requirements (screen readers announcing "flag of France" alongside a country name). Confirm the rendered output is decorative-marked and that visible country names — not flags alone — carry the meaning; flags alone are an accessibility and ambiguity hazard.

Version note: v3.0.1 is a patch release adding Laravel 12.x compatibility. No breaking changes, no new features, no deprecations, no API surface change. Treat it as a routine upgrade and pin to ^3.0.

How to Pitch It (Stakeholders)

For executives — one paragraph: Our new international features need country flags in dropdowns and address forms. This package provides that in a single line of code, is actively maintained, and as of v3.0.1 is compatible with Laravel 12 — so it does not block our framework upgrade. It is a small, narrowly scoped, presentational dependency, not a platform commitment: we keep the flags as versioned assets and can swap the rendering layer without touching product logic. Cost is near zero; the alternative is spending engineering time building and indefinitely maintaining a flag asset pipeline that adds no product differentiation.

For engineering — the short version:

• Single-purpose Blade/helper package for rendering a country flag from an ISO 3166-1 alpha-2 code. It is a view-layer convenience over a maintained flag asset set, not a country-data provider.
• v3.0.1 is a patch: adds Laravel 12.x compatibility only. No breaking changes, no migration work, no deprecations. Upgrade is composer update stidges/laravel-country-flags and pin ^3.0.
• Integration surface is small and easy to isolate: wrap calls in our own x-country-flag component so the dependency is behind one seam. If it is ever abandoned or we need a different flag style, we reimplement one component and nothing else moves.
• Do not use this to answer questions about country metadata — currencies, dial codes, tax, subdivisions. That is a separate concern; raise it as its own ticket rather than extending this dependency.
• Do ensure flag output is marked decorative and that an accessible country name is always rendered in text. Flags alone are ambiguous and screen-reader-hostile.
• Residual risks: single-maintainer project and a fixed visual style from the underlying asset set. Both are contained by the wrapper-component approach above.