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

✨ 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

🚀 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 with size prop

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

export default function App() {
  return (
    <div>
      <FlagJp size="sm" />
      {/* 16px */}
      <FlagDe size="md" />
      {/* 24px */}
      <FlagFr size="lg" />
      {/* 32px */}
    </div>
  )
}

Dynamic flag selection

import { createSignal, lazy } 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>
  )
}

📚 API

Props

| Prop | Type | Default | Description | | -------- | ----------------------------------------------- | ------- | ---------------------------- | | width | number \| string | 48 | Width of the flag | | height | number \| string | 48 | Height of the flag | | size | 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' | - | Preset size | | title | string | - | Accessible title for the SVG |

Size Presets

| Size | Pixels | | ----- | ------ | | xs | 12px | | sm | 16px | | md | 24px | | lg | 32px | | xl | 48px | | 2xl | 64px |

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