react-country-flag, react-flag-kit, react-flags, and react-flags-select are React libraries that help developers render country flags in web applications. These packages differ significantly in implementation strategy — some use SVG sprites or inline SVGs, others rely on external image assets or CSS background images — which affects bundle size, accessibility, customization, and performance. While all aim to simplify flag display, their APIs, maintenance status, and suitability for production vary widely.
Displaying Country Flags in React: A Practical Comparison
When building internationalized React apps — think user profiles, shipping forms, or language selectors — you’ll often need to show country flags. The four packages under review take very different approaches: some embed SVGs directly, others pull remote images, and one even ships a full country picker UI. Let’s cut through the noise and see what actually works in real projects.
🚫 Deprecation Warning: react-flags Is Dead
Before diving into features, let’s address the elephant in the room: react-flags is deprecated. Its npm page states it’s no longer maintained, and its GitHub repo is archived. It loads flags as external PNGs from unpkg, which causes layout shifts and fails offline. Do not use this in new projects. We’ll still compare it for completeness, but treat it as a cautionary tale.
🖼️ How Flags Are Rendered: Inline SVG vs External Images
The biggest technical difference lies in how each package delivers flag graphics — and that choice impacts performance, accessibility, and reliability.
react-country-flag uses inline SVGs embedded directly in the bundle. Each flag is a React component generated from SVG paths.
// react-country-flag
import ReactCountryFlag from "react-country-icon";
<ReactCountryFlag countryCode="US" svg style={{ width: '2em' }} />
react-flag-kit also uses inline SVGs, but with more refined vector paths and consistent aspect ratios. It supports both 2-letter (US) and 3-letter (USA) codes.
// react-flag-kit
import { US } from "react-flag-kit";
<US style={{ width: '2em' }} />
react-flags (deprecated) loads external PNGs from a CDN:
// react-flags (avoid)
import Flag from "react-flags";
<Flag name="USA" basePath="/flags" />
// Tries to load /flags/USA.png — breaks if offline or CDN fails
react-flags-select bundles SVGs as data URLs inside CSS background images by default, though it can switch to inline SVGs via the useSvg prop:
// react-flags-select
import ReactFlagsSelect from "react-flags-select";
<ReactFlagsSelect selected="US" onSelect={code => console.log(code)} useSvg />
💡 Key takeaway: Inline SVGs (used by
react-country-flagandreact-flag-kit) avoid network requests, prevent layout shift, and scale cleanly. External images (like inreact-flags) are fragile and slow.
🔤 Country Code Support and Fallbacks
Not all packages handle invalid or missing country codes gracefully.
react-country-flag silently renders nothing if you pass an unsupported code like XX. You must validate inputs yourself:
// No error thrown for invalid code
<ReactCountryFlag countryCode="XX" /> {/* renders empty */}
react-flag-kit throws a clear error during development if you import a non-existent flag:
// This fails at build time if 'XX' doesn't exist
import { XX } from "react-flag-kit"; // Module not found
react-flags-select includes a built-in list of supported countries and ignores invalid selections:
// Invalid code is just ignored
<ReactFlagsSelect selected="XX" /> {/* shows nothing or placeholder */}
react-flags tries to load XX.png and shows a broken image icon — a poor user experience.
🎨 Customization and Styling
Need to tweak colors, sizes, or add borders? Here’s how each package handles it.
react-country-flag accepts a style prop and lets you force SVG mode (which enables CSS styling):
<ReactCountryFlag
countryCode="FR"
svg
style={{
width: '1.5em',
height: '1em',
border: '1px solid #ccc'
}}
/>
react-flag-kit gives you a plain SVG element, so standard CSS works:
.flag {
width: 1.5em;
filter: grayscale(100%); /* easy to modify */
}
<US className="flag" />
react-flags-select offers extensive theming via CSS classes and props like customLabels, but deep styling requires overriding its internal class names:
<ReactFlagsSelect
selected="DE"
selectButtonClassName="my-custom-button"
optionsClassName="my-options-list"
/>
react-flags provides minimal styling control — you’re stuck with whatever the PNG looks like.
📋 When You Need a Country Picker (Not Just a Flag)
Only react-flags-select includes a complete UI component for selecting countries. The others are display-only.
If your use case is “show the user’s country flag next to their name,” any of the display-focused libraries work. But if you need “let users pick their country from a dropdown,” react-flags-select saves you from building a selector from scratch:
// Full country selector with search
<ReactFlagsSelect
searchable
searchPlaceholder="Search countries..."
onSelect={code => setUserCountry(code)}
/>
The trade-off? You’re pulling in extra code for dropdown logic, even if you only need static flags elsewhere in your app.
♿ Accessibility Considerations
Screen reader support varies:
-
react-country-flagadds a<title>element when you pass atitleprop:<ReactCountryFlag countryCode="JP" title="Japan" /> -
react-flag-kitleaves accessibility up to you — wrap the SVG in a<span aria-label="Japan">if needed. -
react-flags-selectincludes ARIA labels for its dropdown options automatically. -
react-flagsoffers no built-in accessibility features.
🧪 Real-World Recommendation
| Scenario | Best Choice |
|---|---|
| Simple flag display with minimal bundle | react-country-flag |
| High-fidelity flags for polished UIs | react-flag-kit |
| Country selection dropdown | react-flags-select |
| New projects (any use case) | Avoid react-flags |
Final Advice
- For static flags, prefer
react-flag-kitif visual quality matters, orreact-country-flagif you want the smallest possible footprint. - For country input forms,
react-flags-selectis the only complete solution here — just be mindful of its bundle cost. - Never use
react-flags— it’s outdated, unreliable, and unmaintained.
Choose based on whether you need just a flag or a full selection interface, and always validate country codes before rendering to avoid silent failures.
- react-country-flag:
Choose
react-country-flagif you need a lightweight, zero-dependency solution that renders flags as inline SVGs using ISO 3166-1 alpha-2 codes. It’s ideal for simple flag displays where accessibility (viatitleattributes) and minimal bundle impact matter. Avoid it if you require fallback handling for unsupported codes or advanced styling beyond basic props likesvgandstyle. - react-flags:
Do not choose
react-flagsfor new projects. The package is deprecated according to its npm registry entry and GitHub repository archive status. It relies on external PNG assets hosted via unpkg, introduces layout shift due to image loading, and lacks modern accessibility features. Use one of the maintained alternatives instead. - react-flags-select:
Choose
react-flags-selectif you need a ready-made country selector dropdown with integrated flag display, search, and localization support. It’s well-suited for forms requiring country input (e.g., phone number or address fields). However, its bundle includes all flag assets by default, so consider lazy-loading or custom builds if bundle size is a concern. - react-flag-kit:
Choose
react-flag-kitif you want high-quality, consistent SVG flags with excellent visual fidelity and built-in support for both ISO 2-letter and 3-letter country codes. Its clean API and focus on design quality make it suitable for UIs where visual polish is critical. However, note that it doesn’t include selection UI components — it’s purely for rendering individual flags.
react-country-flag
React component for emoji/svg country flags.
Install
npm install --save react-country-flag
BREAKING CHANGES
v3.x NONE only Typescript Types were introduced, enjoy!
v2.x has breaking changes
codeis nowcountryCodetitleandaria-labelare not defined any more, it is up to the developer to pass these instylePropsis nowstyle
Usage
All props are passed onto the element, everything can be overwritten.
import React from "react"
import ReactCountryFlag from "react-country-flag"
function ExampleComponent {
return (
<div>
<ReactCountryFlag countryCode="US" />
<ReactCountryFlag
className="emojiFlag"
countryCode="US"
style={{
fontSize: '2em',
lineHeight: '2em',
}}
aria-label="United States"
/>
<ReactCountryFlag countryCode="US" svg />
<ReactCountryFlag
countryCode="US"
svg
style={{
width: '2em',
height: '2em',
}}
title="US"
/>
<ReactCountryFlag
countryCode="US"
svg
cdnUrl="https://cdnjs.cloudflare.com/ajax/libs/flag-icon-css/3.4.3/flags/1x1/"
cdnSuffix="svg"
title="US"
/>
</div>
)
}
export default ExampleComponent
Detecting Emoji support
Try this out and conditionally render your country flag https://github.com/danalloway/detect-emoji-support
License
MIT © danalloway