circle-flags-ui

400+ circular SVG flag components for React, Vue 3, and Solid.js

🚀 Demo Gallery · 📖 Documentation · 🐛 Issues

---

📦 Package Matrix

Framework	Package	Status	Live Demo	Docs
React	@sankyu/react-circle-flags			README
Vue 3	@sankyu/vue-circle-flags			README
Solid.js	@sankyu/solid-circle-flags			README

✨ Features

• 🎯 Tree-shakable — Only bundle the flags you actually use
• 📦 TypeScript — Full type definitions for all 400+ flags
• ⚡ Offline-first — Inline SVG, zero runtime network requests
• 🔧 Customizable — All standard SVG props supported (width, height, className, ...)
• 📱 SSR-friendly — Works with Next.js, Nuxt, SolidStart, and more
• 🪶 Lightweight — ~1 KB per flag component
• 🧩 Shared core — Single source of truth, framework-specific output

🚀 Quick Start

Pick the package for your framework and install it:

# React
pnpm add @sankyu/react-circle-flags

# Vue 3
pnpm add @sankyu/vue-circle-flags

# Solid.js
pnpm add @sankyu/solid-circle-flags

Then import named flag components directly:

// React example
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>
  )
}

See per-package READMEs for Vue and Solid usage examples.

🤖 Vibe Coding?

Paste this prompt into your AI agent (Claude, Cursor, Codex, etc.) to migrate or optimize flag usage in your project:

AI Agent Prompt

Act as an expert Web Engineer. Reference: https://react-circle-flags.js.org/llms.txt & https://react-circle-flags.js.org/llms-small.txt

1. Audit my project to find any flag usage:
   - Raw <img> tags pointing to HatScripts/circle-flags URLs.
   - Legacy react-circle-flags library usage.
2. Propose a migration to the appropriate @sankyu/{framework}-circle-flags package based on my framework (React/Vue/Solid).
3. Optimize for Tree-shaking: replace generic CircleFlag components with named imports (e.g. import { FlagUs } from '...') as per the docs.

🛠️ Monorepo Development

# Install dependencies
pnpm install

# Generate flag components from source SVGs
pnpm run gen:flags

# Build all packages
pnpm run build

# Quality checks
pnpm run lint
pnpm run typecheck
pnpm run test

📂 Repository Layout

circle-flags-ui/
├── packages/
│   ├── core/      # shared types, utils, generated registry (private)
│   ├── react/     # @sankyu/react-circle-flags
│   ├── vue/       # @sankyu/vue-circle-flags
│   └── solid/     # @sankyu/solid-circle-flags
├── examples/      # per-framework example apps
├── scripts/       # generation / build / release scripts
└── website/       # documentation site (Astro)

Credits

Flag designs from HatScripts/circle-flags.

License

• Repository and packages: MIT © Sankyu Lab
• website/: GPL-3.0 (see website/LICENSE)