Basic Usage

Import strategies

Choose the right approach based on your use case:

1. Named Imports (Recommended)

2. DynamicFlag (Offline, Large Bundle)

1. Named Imports

When to use

Use named imports when you:

• 📦 Work offline or in restricted network environments
• ✅ Know which flags you need at build time
• 🚀 Want synchronous rendering without loading states

Best for static flags known at build time.

• Bundle impact: ~950 bytes per flag
• Tree-shaking: ✅ Excellent
• Loading: Synchronous, instant

Import only the flags you need from the main entry:

React

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

export function Header() {
  return (
    <div>
      <FlagUs width={32} height={32} />
      <FlagCn width={32} height={32} />
      <FlagGb width={32} height={32} />
    </div>
  )
}

Vue 3

<script setup lang="ts">
import { FlagUs, FlagCn, FlagGb } from '@sankyu/vue-circle-flags'
</script>

<template>
  <div>
    <FlagUs :width="32" :height="32" />
    <FlagCn :width="32" :height="32" />
    <FlagGb :width="32" :height="32" />
  </div>
</template>

Solid.js

Solid (beta): named-import flags currently use className for CSS classes.

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

export function Header() {
  return (
    <div>
      <FlagUs width={32} height={32} className="flag-icon" />
      <FlagCn width={32} height={32} className="flag-icon" />
      <FlagGb width={32} height={32} className="flag-icon" />
    </div>
  )
}

API Reference

See full props definition: FlagComponentProps →

2. DynamicFlag

When to use

Use DynamicFlag when you:

• ⚡ Need to render any flag synchronously from runtime ISO codes
• ❌ Cannot access external CDNs (offline, intranet, air-gapped)
• 🛠️ Want full SVG props support (direct <svg /> rendering)

Large Bundle Impact

This component adds ~600 KB to your bundle (it bundles ALL 400+ flags).

Offline-first runtime flags (bundles all flags).

• Bundle impact: ~600 KB
• Tree-shaking: ❌ None
• Loading: Synchronous, instant

Render any flag from runtime ISO codes without network requests:

React

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

export function CountryFlag({ code }: { code: string }) {
  return <DynamicFlag code={code} width={36} height={36} />
}

Vue 3

<script setup lang="ts">
import { DynamicFlag } from '@sankyu/vue-circle-flags'
const props = defineProps<{ code: string }>()
</script>

<template>
  <DynamicFlag :code="props.code" :width="36" :height="36" />
</template>

Solid.js

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

export function CountryFlag(props: { code: string }) {
  return <DynamicFlag code={props.code} width={36} height={36} />
}

API Reference

See full props definition: DynamicFlagProps →

Naming convention

All flag components follow a consistent naming pattern:

Pattern

Components use the format Flag{ISO} where ISO is the uppercase country code.

Examples

• FlagUs → United States

• FlagCn → China

• FlagGb → United Kingdom

• FlagJp → Japan

Framework examples

The library works seamlessly with all modern frameworks:

Next.js

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

export default function Page() {
  return (
    <main>
      <h1>Country Flags</h1>
      <div className="flex gap-4">
        <FlagUs width={64} height={64} />
        <FlagCn width={64} height={64} />
      </div>
    </main>
  )
}

Remix

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

export default function Index() {
  return (
    <div>
      <h1>Country Flags</h1>
      <div className="flex gap-4">
        <FlagUs width={48} height={48} />
        <FlagCn width={48} height={48} />
      </div>
    </div>
  )
}

Vite (React)

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

function App() {
  return (
    <>
      <h1>Country Flags</h1>
      <div className="flex gap-4">
        <FlagUs width={56} height={56} />
        <FlagCn width={56} height={56} />
      </div>
    </>
  )
}

export default App

SolidStart

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

export default function Home() {
  return (
    <main>
      <h1>Country Flags</h1>
      <div class="flex gap-4">
        <FlagUs width={64} height={64} className="rounded-full" />
        <FlagCn width={64} height={64} className="rounded-full" />
      </div>
    </main>
  )
}

Vite (Solid)

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

export default function App() {
  return (
    <main>
      <h1>Country Flags</h1>
      <div class="flex gap-4">
        <FlagUs width={56} height={56} className="rounded-full" />
        <FlagCn width={56} height={56} className="rounded-full" />
      </div>
    </main>
  )
}

Nuxt.js

<script setup lang="ts">
import { FlagUs, FlagCn } from '@sankyu/vue-circle-flags'
</script>

<template>
  <main>
    <h1>Country Flags</h1>
    <div class="flex gap-4">
      <FlagUs :width="64" :height="64" />
      <FlagCn :width="64" :height="64" />
    </div>
  </main>
</template>

Vue 3

<script setup lang="ts">
import { FlagUs, FlagCn } from '@sankyu/vue-circle-flags'
</script>

<template>
  <div>
    <h1>Country Flags</h1>
    <div class="flex gap-4">
      <FlagUs :width="48" :height="48" />
      <FlagCn :width="48" :height="48" />
    </div>
  </div>
</template>

Next steps

Bundle Size Optimization Compare bundle sizes and choose the best strategy

Styling Customize flag appearance with CSS and inline styles

Dynamic Flags Render flags from runtime ISO codes (offline-first strategies)