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

For guaranteed per-flag isolation across Vite, webpack, and framework SSR bundlers, import each component from its flags/* subpath:

React

import { FlagUs } from '@sankyu/react-circle-flags/flags/us'
import { FlagCn } from '@sankyu/react-circle-flags/flags/cn'
import { FlagGb } from '@sankyu/react-circle-flags/flags/gb'

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 } from '@sankyu/vue-circle-flags/flags/us'
import { FlagCn } from '@sankyu/vue-circle-flags/flags/cn'
import { FlagGb } from '@sankyu/vue-circle-flags/flags/gb'
</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 } from '@sankyu/solid-circle-flags/flags/us'
import { FlagCn } from '@sankyu/solid-circle-flags/flags/cn'
import { FlagGb } from '@sankyu/solid-circle-flags/flags/gb'

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>
  )
}

Svelte 5

<script lang="ts">
  import FlagUs from '@sankyu/svelte-circle-flags/flags/us'
  import FlagCn from '@sankyu/svelte-circle-flags/flags/cn'
  import FlagGb from '@sankyu/svelte-circle-flags/flags/gb'
</script>

<div>
  <FlagUs width={32} height={32} />
  <FlagCn width={32} height={32} />
  <FlagGb width={32} height={32} />
</div>

The shorter main-entry form (import { FlagUs } from '@sankyu/react-circle-flags') remains supported. Use the explicit subpath when bundle size must be deterministic, because the main entry also exposes DynamicFlag and its complete registry.

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} />
}

Svelte 5

<script lang="ts">
  import { DynamicFlag } from '@sankyu/svelte-circle-flags'

  let { code }: { code: string } = $props()
</script>

<DynamicFlag {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 App Router (SSR)

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>
  )
}

React + Vite 8

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

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 4 (SSR)

<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 + Vite 8

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

Svelte 5 + Vite 8

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

<main>
  <h1>Country Flags</h1>
  <div class="flags">
    <FlagUs width={48} height={48} />
    <FlagCn width={48} height={48} />
  </div>
</main>

The repository includes build-tested Next.js SSR, Nuxt SSR, and Vite examples. For SSR boundaries, bundle trade-offs, and troubleshooting, see the SSR compatibility guide.

Next steps

Bundle Size OptimizationCompare bundle sizes and choose the best strategy

StylingCustomize flag appearance with CSS and inline styles

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