@sankyu/react-circle-flags

:star: Star us on GitHub | :bug: Report Issues here

:rocket: Explore the Demo Gallery | :book: Read the Documentation

📖 Overview

This library provides 400+ circular SVG flag components with Full-TypeScript support & Tree-shaking Optimization.

Perfect for applications that need fast, crisp country flags without external image requests.

✨ Key Features

[!TIP] For more information, you may refer to the Documentation.

• 🎯 Tree-shakable - Only bundle the flags you use
• 📦 TypeScript - Full type definitions included
• ⚡ Zero dependencies - Only requires React as peer dependency
• 🎨 Inline SVG - No external requests, works offline
• 🔧 Fully customizable - All standard SVG props supported
• 📱 SSR compatible - Works with Next.js, Remix, etc.
• 🪶 Lightweight - Each flag is ~1KB

📦 Installation

npm install @sankyu/react-circle-flags
# or
pnpm add @sankyu/react-circle-flags
# or
yarn add @sankyu/react-circle-flags
# or
bun add @sankyu/react-circle-flags

[!TIP] For more information, you may refer to the Installation Guide.

🚀 Usage

Import individual flags (Recommended)

import { FlagUs, FlagCn, FlagGb } from '@sankyu/react-circle-flags'

export default function App() {
  return (
    <div>
      <FlagUs width={48} height={48} />
      <FlagCn width={48} height={48} />
      <FlagGb width={48} height={48} />
    </div>
  )
}

Other usage examples

[!TIP] For more information, you may refer to the Usage Guide.

📚 API

Build Meta Information

You can access the library's build meta information from the buildMeta export:

import { buildMeta } from '@sankyu/react-circle-flags'

console.log(buildMeta.version) // e.g., "1.2.3"
console.log(buildMeta.builtTimestamp) // e.g., 1760000000000
console.log(buildMeta.commitHash) // e.g., <example-sha256-hash>
console.log(buildMeta.circleFlagsCommitHash) // e.g., <example-sha256-hash>

Other Props

...For more information, you may refer to the API Reference.

Available Flags

Each flag is exported with the pattern Flag{PascalCase ISO_CODE} (for example, FlagUs, FlagCn). Convenience aliases are provided for common two-letter codes: FlagUs, FlagCn, FlagGb, FlagJp.

• FlagUs - United States
• FlagCn - China
• FlagGb - United Kingdom
• FlagJp - Japan
• ... and many more

See the Full list of flags in the react-circle-flags gallery.

🎨 Styling

Flag components accept all standard SVG props, making them easy to style with any CSS approach.

[!TIP] For more information, you may refer to the Styling Guide.

🔧 TypeScript

All flag components are fully typed with TypeScript, providing autocomplete and type safety out of the box.

[!TIP] For more information, you may refer to the TypeScript Guide.

📖 Examples

[!TIP] For more information, you may refer to the Guide - Basic Usage.

📦 Bundle Size & Tree-shaking

@sankyu/react-circle-flags is designed to be tree-shakable.

Importing individual flags ensures that only the used flags are included in your bundle.

[!TIP] For more information, you may refer to the Bundle Size & Tree-shaking Guide.

🤝 Contributing

Please see CONTRIBUTING.md for contribution guidelines.

📄 License

@sankyu/react-circle-flags is licensed under the MIT License, © Sankyu Lab

website is licensed under the GPL-3.0 License, © Sankyu Lab

🙏 Credits

• Flag designs from HatScripts/circle-flags
• Built with tsup