Dynamic Flags

Decision guide

You can enumerate the possible codes (finite set): use Named Imports + Map (recommended)
You need to render any code synchronously and stay offline: use DynamicFlag

Why runtime flags?

In many apps, country codes come from runtime data:

User-selected countries (forms, settings)
API/database values (profiles, records)
Location-based content

Strategy 1: Named Imports + Map (Recommended)

This stays offline-first while still letting you render runtime values.

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

const FLAGS = {
  cn: FlagCn,
  gb: FlagGb,
  us: FlagUs,
} as const

export function CountryFlag({ code }: { code: string }) {
  const normalized = code.toLowerCase()
  const Flag = FLAGS[normalized as keyof typeof FLAGS]

  if (!Flag) return <span title="Unknown country code">{code.toUpperCase()}</span>
  return <Flag width={36} height={36} />
}

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

const props = defineProps<{ code: string }>()

const FLAGS = {
  cn: FlagCn,
  gb: FlagGb,
  us: FlagUs,
} as const

const FlagComp = computed(() => {
  const normalized = props.code.toLowerCase()
  return FLAGS[normalized as keyof typeof FLAGS] ?? null
})
</script>

<template>
  <component v-if="FlagComp" :is="FlagComp" :width="36" :height="36" />
  <span v-else :title="'Unknown country code'">{{ props.code.toUpperCase() }}</span>
</template>

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

const FLAGS = {
  cn: FlagCn,
  gb: FlagGb,
  us: FlagUs,
} as const

export function CountryFlag(props: { code: string }) {
  const normalized = props.code.toLowerCase()
  const Flag = FLAGS[normalized as keyof typeof FLAGS]

  if (!Flag) return <span title="Unknown country code">{props.code.toUpperCase()}</span>
  return <Flag width={36} height={36} />
}

Strategy 2: DynamicFlag (Offline, Bundles All Flags)

Use this when you truly need to support any runtime code and still render synchronously with full SVG props.

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

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

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

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

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

Strict typing (optional)

If you can guarantee that your runtime value is already a valid country code (for example, from a typed list), enable strict for stronger TypeScript constraints:

React
Vue 3

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

export function CountryFlag({ codeFromApi }: { codeFromApi: string }) {
  // Coerce unknown runtime data to a safe union (unknown values become "xx")
  const safeCode = coerceFlagCode(codeFromApi)
  return <DynamicFlag strict code={safeCode} width={36} height={36} />
}

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

const props = defineProps<{ codeFromApi: string }>()
const safeCode = computed(() => coerceFlagCode(props.codeFromApi))
</script>

<template>
  <DynamicFlag strict :code="safeCode" :width="36" :height="36" />
</template>

Quick comparison

Strategy	Bundle impact	Network	Offline-first
Named Imports + Map	~950 bytes per imported flag	None	✅
DynamicFlag	~600 KB	None	✅

Next step

Bundle Size Learn about bundle size optimization and tree-shaking strategies