react-flags-select is a React library that provides highly customizable SVG flag components designed for selection interfaces and individual country flag display. It enables developers to integrate a dropdown-style country selector with features such as search, custom labels, blacklisting specific countries, and dynamic sizing. Additionally, it exports standalone SVG components for each country flag (e.g., `<Us />` for the United States), allowing for flexible display beyond the selector. The current stable version is 2.5.0, and the package ships with comprehensive TypeScript type definitions, enhancing development with type safety. Key differentiators include its fine-grained control over the displayed flag list, robust support for flexible custom labeling, and the provision of both a comprehensive selector component and individual flag SVGs, catering to diverse internationalization and country display needs within React applications. Its design focuses on ease of integration and customization.
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
The primary `ReactFlagsSelect` component is a default export.
import ReactFlagsSelect from 'react-flags-select';
Individual country flag components are named exports, using their ISO 3166-1 alpha-2 codes (e.g., `Us`, `Gb`, `Fr`). Replace `Us` with the desired country code.
import { Us } from 'react-flags-select';
Use `CountryCode` for type safety when working with country codes, particularly for parameters like the `onSelect` callback argument, as it is an exported type.
import type { CountryCode } from 'react-flags-select';
This quickstart demonstrates the `ReactFlagsSelect` component with common props like `selected`, `onSelect`, `countries`, `placeholder`, `searchable`, and `customLabels` (showing both string and object formats). It also includes a basic example of displaying the flag for the currently selected country using a public API, illustrating a common use case alongside the primary selector.
import React, { useState } from "react";
import ReactFlagsSelect from "react-flags-select";
function App() {
const [selectedCountry, setSelectedCountry] = useState<string>("US");
return (
<div style={{ padding: "20px", fontFamily: "sans-serif", maxWidth: "400px", margin: "auto" }}>
<h1>Select Your Country</h1>
<p>Currently selected: <strong>{selectedCountry || "None"}</strong></p>
<ReactFlagsSelect
selected={selectedCountry}
onSelect={(code: string) => {
setSelectedCountry(code);
console.log(`Selected country code: ${code}`);
}}
countries={["US", "GB", "CA", "FR", "DE", "JP", "AU", "NG"]}
placeholder="Select a country..."
searchable
searchPlaceholder="Find a country..."
customLabels={{
US: { primary: "United States", secondary: "+1" },
GB: { primary: "United Kingdom", secondary: "+44" },
FR: "France", // Mixed usage example
DE: "Germany",
CA: "Canada",
NG: { primary: "Nigeria", secondary: "+234" }
}}
className="menu-flags" // Example of custom class for styling
selectedSize={18}
optionsSize={14}
fullWidth={false}
/>
<div style={{ marginTop: "30px", fontSize: "20px", borderTop: "1px solid #eee", paddingTop: "20px" }}>
<h2>Individual Flag Display:</h2>
{selectedCountry ? (
<p>
Selected: <img src={`https://flagsapi.com/${selectedCountry}/flat/64.png`} alt={selectedCountry} style={{ verticalAlign: 'middle', marginRight: '8px' }} />
({selectedCountry})
</p>
) : (
<p>Select a country above to see its flag here.</p>
)}
<p style={{ marginTop: "15px" }}>
Example: <img src={`https://flagsapi.com/JP/flat/64.png`} alt="Japan" style={{ verticalAlign: 'middle', marginRight: '8px' }} />
Japan (JP)
</p>
</div>
</div>
);
}
export default App;
// To integrate this in a typical React application, ensure your root rendering file (e.g., index.tsx)
// renders the <App /> component. E.g.:
// import React from 'react';
// import ReactDOM from 'react-dom/client';
// import App from './App';
// const root = ReactDOM.createRoot(document.getElementById('root') as HTMLElement);
// root.render(<React.StrictMode><App /></React.StrictMode>);
Upgrade
Version history
Breaking-change detection hasn't run for this library yet.
Audit
Security & dependencies
CVE tracking and dependency tree are planned for a later release.