TypeScript

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

SVG prop typing

React

All flag components accept standard React SVG props:

import type { SVGProps } from 'react'
import { FlagUs } from '@sankyu/react-circle-flags'

interface Props {
  flagProps?: SVGProps<SVGSVGElement>
}

export function FlagItem({ flagProps }: Props) {
  return <FlagUs {...flagProps} />
}

Vue 3

All flag components accept standard Vue SVG props:

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

interface Props {
  flagProps?: SVGAttributes
}

const props = defineProps<Props>()
</script>

<template>
  <FlagUs v-bind="props.flagProps" />
</template>

Solid.js

All flag components accept standard Solid SVG props:

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

interface Props {
  flagProps?: JSX.SvgSVGAttributes<SVGSVGElement>
}

export function FlagItem(props: Props) {
  return <FlagUs {...props.flagProps} />
}

Svelte 5

All flag components accept standard Svelte SVG attributes:

<script lang="ts">
  import FlagUs from '@sankyu/svelte-circle-flags/flags/us'
  import type { SVGAttributes } from 'svelte/elements'

  let { flagProps = {} }: { flagProps?: SVGAttributes<SVGSVGElement> } = $props()
</script>

<FlagUs {...flagProps} />

Type Inference

TypeScript will automatically infer all available props when you use flag components. No additional type imports are required for basic usage.

Advanced typing examples

Component Props

import type { SVGProps, ComponentProps } from 'react'
import { FlagCn } from '@sankyu/react-circle-flags'

// Method 1: Using SVGProps
type FlagProps1 = SVGProps<SVGSVGElement>

// Method 2: Using ComponentProps (recommended)
type FlagProps2 = ComponentProps<typeof FlagCn>

export function Flag(props: FlagProps2) {
  return <FlagCn {...props} />
}

Reusable Wrapper

import type { ComponentProps, ComponentType } from 'react'
import { FlagUs } from '@sankyu/react-circle-flags'

type SvgFlagProps = ComponentProps<typeof FlagUs>
type SvgFlagComponent = ComponentType<SvgFlagProps>

interface FlagWithLabelProps extends SvgFlagProps {
  FlagComponent?: SvgFlagComponent
  label?: string
}

export function FlagWithLabel({
  FlagComponent = FlagUs,
  label,
  ...svgProps
}: FlagWithLabelProps) {
  return (
    <div>
      <FlagComponent {...svgProps} />
      {label && <span>{label}</span>}
    </div>
  )
}

Event Handlers

import type { MouseEvent } from 'react'
import { FlagJp } from '@sankyu/react-circle-flags'

export function InteractiveFlag() {
  const handleClick = (e: MouseEvent<SVGSVGElement>) => {
    console.log('Flag clicked at', e.clientX, e.clientY)
  }

  return (
    <FlagJp
      width={48}
      height={48}
      onClick={handleClick}
      style={{ cursor: 'pointer' }}
    />
  )
}

Solid.js

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

type FlagCnProps = Parameters<typeof FlagCn>[0]
type SvgFlagProps = Parameters<typeof FlagUs>[0]
type SvgFlagComponent = Component<SvgFlagProps>

export function Flag(props: FlagCnProps) {
  return <FlagCn {...props} />
}

export function FlagWithLabel(
  props: { FlagComponent?: SvgFlagComponent; label?: string } & SvgFlagProps
) {
  const { FlagComponent = FlagUs, label, ...svgProps } = props
  return (
    <div>
      <FlagComponent {...svgProps} />
      {label && <span>{label}</span>}
    </div>
  )
}

Svelte 5

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

  let props: ComponentProps<typeof FlagUs> = {
    width: 48,
    height: 48,
    title: 'United States',
  }
</script>

<FlagUs {...props} />

Type exports

The library exports helpful types for advanced use cases:

React

import { coerceFlagCode, isFlagCode } from '@sankyu/react-circle-flags'
import type { CountryCode, FlagCode, FlagComponentProps } from '@sankyu/react-circle-flags'

// FlagCode: Union type of all available flag codes
const validCode: FlagCode = 'us' // ✓ Valid
const invalidCode: FlagCode = 'invalid' // ✗ Type error

// CountryCode: a semantic alias of FlagCode (same union)
const alsoValid: CountryCode = validCode

// FlagComponentProps: Standard props for flag components
const props: FlagComponentProps = {
  width: 64,
  height: 64,
  className: 'my-flag',
}

// Runtime data narrowing/coercion helpers
const fromApi: string = 'US'
const safeCode = coerceFlagCode(fromApi) // -> FlagCode (unknown values become "xx")
const isNormalizedValid = isFlagCode('us') // true (expects already-normalized input)

Vue 3

import { coerceFlagCode, isFlagCode } from '@sankyu/vue-circle-flags'
import type { CountryCode, FlagCode, FlagComponentProps } from '@sankyu/vue-circle-flags'

// FlagCode: Union type of all available flag codes
const validCode: FlagCode = 'us' // ✓ Valid
const invalidCode: FlagCode = 'invalid' // ✗ Type error

// CountryCode: a semantic alias of FlagCode (same union)
const alsoValid: CountryCode = validCode

// FlagComponentProps: Standard props for flag components
const props: FlagComponentProps = {
  width: 64,
  height: 64,
  className: 'my-flag',
}

const fromApi: string = 'US'
const safeCode = coerceFlagCode(fromApi)
const isNormalizedValid = isFlagCode('us')

Solid.js

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

// FlagCode: Union type of all available flag codes
const validCode: FlagCode = 'us' // ✓ Valid
const invalidCode: FlagCode = 'invalid' // ✗ Type error

// CountryCode: a semantic alias of FlagCode (same union)
const alsoValid: CountryCode = validCode

// FlagComponentProps: Standard props for flag components
const props: FlagComponentProps = {
  width: 64,
  height: 64,
  className: 'my-flag',
}

const fromApi: string = 'US'
const safeCode = coerceFlagCode(fromApi)
const isNormalizedValid = isFlagCode('us')

Svelte 5

import { coerceFlagCode, isFlagCode } from '@sankyu/svelte-circle-flags'
import type {
  CountryCode,
  DynamicFlagProps,
  FlagCode,
  FlagComponentProps,
} from '@sankyu/svelte-circle-flags'

const validCode: FlagCode = 'us'
const alsoValid: CountryCode = validCode

const props: FlagComponentProps = {
  width: 64,
  height: 64,
  className: 'my-flag',
}

const strictProps: DynamicFlagProps = {
  strict: true,
  code: validCode,
}

const safeCode = coerceFlagCode('US')
const isNormalizedValid = isFlagCode('us')

Flag code utilities

React

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

// Convert country code to component name (PascalCase)
FlagUtils.getComponentName('us') // 'FlagUs'
FlagUtils.getComponentName('gb-eng') // 'FlagGbEng'

// Normalize display format (uppercase)
FlagUtils.formatCountryCode('us') // 'US'

Vue 3

import { FlagUtils } from '@sankyu/vue-circle-flags'

FlagUtils.getComponentName('us') // 'FlagUs'
FlagUtils.formatCountryCode('us') // 'US'

Solid.js

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

FlagUtils.getComponentName('us') // 'FlagUs'
FlagUtils.formatCountryCode('us') // 'US'

Svelte 5

import { FlagUtils } from '@sankyu/svelte-circle-flags'

FlagUtils.getComponentName('us') // 'FlagUs'
FlagUtils.formatCountryCode('us') // 'US'

FlagUtils toolkit

The FlagUtils object provides convenient utility functions for working with flag codes:

React

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

// Validate country codes
FlagUtils.isValidCountryCode('us')    // true
FlagUtils.isValidCountryCode('invalid') // false

// Format country codes
FlagUtils.formatCountryCode('us')     // "US"

// Get component names
FlagUtils.getComponentName('us')      // "FlagUs"

// Handle flag sizes
FlagUtils.getSizeName(48)             // "lg"
FlagUtils.sizes.lg                    // 48

Vue 3

import { FlagUtils } from '@sankyu/vue-circle-flags'

FlagUtils.isValidCountryCode('us')    // true
FlagUtils.formatCountryCode('us')     // "US"
FlagUtils.getComponentName('us')      // "FlagUs"
FlagUtils.getSizeName(48)             // "lg"
FlagUtils.sizes.lg                    // 48

Solid.js

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

FlagUtils.isValidCountryCode('us')    // true
FlagUtils.formatCountryCode('us')     // "US"
FlagUtils.getComponentName('us')      // "FlagUs"
FlagUtils.getSizeName(48)             // "lg"
FlagUtils.sizes.lg                    // 48

Svelte 5

import { FlagUtils } from '@sankyu/svelte-circle-flags'

FlagUtils.isValidCountryCode('us') // true
FlagUtils.formatCountryCode('us') // "US"
FlagUtils.getComponentName('us') // "FlagUs"
FlagUtils.getSizeName(48) // "lg"
FlagUtils.sizes.lg // 48

Type safety with DynamicFlag

React

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

interface CountrySelectProps {
  selectedCountry: FlagCode
  onSelect: (code: FlagCode) => void
}

export function CountrySelect({ selectedCountry, onSelect }: CountrySelectProps) {
  return (
    <div>
      <DynamicFlag strict code={selectedCountry} width={32} height={32} />
      <button onClick={() => onSelect('us')}>USA</button>
      <button onClick={() => onSelect('cn')}>China</button>
    </div>
  )
}

Vue 3

<script setup lang="ts">
import { ref } from 'vue'
import { DynamicFlag } from '@sankyu/vue-circle-flags'
import type { FlagCode } from '@sankyu/vue-circle-flags'

const selectedCountry = ref<FlagCode>('us')
</script>

<template>
  <DynamicFlag strict :code="selectedCountry" :width="32" :height="32" />
  <button @click="selectedCountry = 'us'">USA</button>
  <button @click="selectedCountry = 'cn'">China</button>
</template>

Solid.js

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

export function CountrySelect() {
  const [selectedCountry, setSelectedCountry] = createSignal<FlagCode>('us')

  return (
    <div>
      <DynamicFlag strict code={selectedCountry()} width={32} height={32} />
      <button onClick={() => setSelectedCountry('us')}>USA</button>
      <button onClick={() => setSelectedCountry('cn')}>China</button>
    </div>
  )
}

Svelte 5

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

  let selectedCountry = $state<FlagCode>('us')
</script>

<DynamicFlag strict code={selectedCountry} width={32} height={32} />
<button onclick={() => (selectedCountry = 'us')}>USA</button>
<button onclick={() => (selectedCountry = 'cn')}>China</button>

Strict Type Checking

Enable strict: true in your tsconfig.json to catch type errors early and get the best TypeScript experience.

Next step

Bundle Size & Tree-shakingLearn how to optimize your bundle size with proper import strategies