@sankyu/solid-circle-flags

English Version

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

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

[!NOTE] 🚧 Beta Release

This package is currently in beta. APIs may change in future releases. Please report any issues you encounter!

📖 Overview

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

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

:world_map: Live Demo

✨ Key Features

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

📦 Installation

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

🤖 Are you Vibe Coding?

Copy this into your AI Agent (Claude Code, Codex, Cursor ..like) to optimize your flags:

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 current framework (React/Vue/Solid).
3. **Optimize for Tree-shaking**: Replace generic `CircleFlag` components or raw tags with **named imports** (e.g., `import { Us } from '...'`) as per the docs.

🚀 Usage

Import individual flags (Recommended)

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

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

Using FlagSizes presets

import { FlagJp, FlagDe, FlagFr, FlagSizes } from '@sankyu/solid-circle-flags'

export default function App() {
  return (
    <div>
      <FlagJp width={FlagSizes.sm} height={FlagSizes.sm} />
      {/* 24px */}
      <FlagDe width={FlagSizes.md} height={FlagSizes.md} />
      {/* 32px */}
      <FlagFr width={FlagSizes.lg} height={FlagSizes.lg} />
      {/* 48px */}
    </div>
  )
}

Dynamic flag selection

import { createSignal } from 'solid-js'
import { DynamicFlag } from '@sankyu/solid-circle-flags'

export default function App() {
  const [countryCode, setCountryCode] = createSignal('us')

  return (
    <div>
      <DynamicFlag code={countryCode()} width={48} height={48} />
      <button onClick={() => setCountryCode('cn')}>Change to China</button>
    </div>
  )
}

[!CAUTION] DynamicFlag is offline-first and renders runtime codes synchronously, but it bundles all 400+ flags (~600 KB, no tree-shaking). Prefer named imports when possible. If runtime codes are bounded, use a finite named-import map.

📚 API

Props

| Prop | Type | Default | Description | | ----------- | ------------------ | ------- | ---------------------------- | | width | number \| string | 48 | Width of the flag | | height | number \| string | 48 | Height of the flag | | title | string | code | Accessible title for the SVG | | class | string | - | Standard Solid class binding | | className | string | - | Optional className alias |

Size Presets

| Size | Pixels | | ------ | ------ | | xs | 16px | | sm | 24px | | md | 32px | | lg | 48px | | xl | 64px | | xxl | 96px | | xxxl | 128px |

Build Meta Information

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

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

console.log(buildMeta.version) // e.g., "0.0.1"
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>

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 gallery.

🎨 Styling

Flag components accept all standard SVG attributes and can be styled using Solid's class binding.

import { FlagUs } from '@sankyu/solid-circle-flags'

export default function App() {
  return (
    <>
      {/* Using class */}
      <FlagUs class="rounded-full shadow-lg hover:scale-110 transition-transform" />

      {/* Using inline styles */}
      <FlagUs style={{ filter: 'grayscale(100%)' }} />

      {/* With custom attributes */}
      <FlagUs aria-label="United States flag" role="img" />
    </>
  )
}

🔧 TypeScript

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

import type { FlagComponentProps, FlagCode } from '@sankyu/solid-circle-flags'

// FlagCode is a union type of all valid flag codes
const code: FlagCode = 'us' // ✓ Valid
const invalid: FlagCode = 'xyz' // ✗ Type error

📦 Bundle Size & Tree-shaking

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

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

// ✓ Good - only FlagUs and FlagCn are bundled
import { FlagUs, FlagCn } from '@sankyu/solid-circle-flags'

🤝 Contributing

Please see CONTRIBUTING.md for contribution guidelines.

📄 License

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

🙏 Credits

• Flag designs from HatScripts/circle-flags
• Built with tsup and esbuild-plugin-solid