Bundle Size & Tree-shaking

Optimize your bundle size by choosing the right approach for your use case.

Import strategies overview

1. Named Imports

• Best for: Static flags known at build time
• Bundle impact: ~950 bytes per flag
• Tree-shaking: ✅ Excellent
• Loading: Synchronous, instant

View detailed usage with code examples →

2. CircleFlag

• Best for: Dynamic flags with minimal bundle
• Bundle impact: ~2 KB (component only)
• Tree-shaking: ✅ Perfect
• Loading: Async from CDN

View detailed usage with code examples →

3. DynamicFlag

• Best for: CDN-restricted environments, offline apps
• Bundle impact: ~600 KB (all flags bundled)
• Tree-shaking: ❌ None
• Loading: Synchronous, instant

View detailed usage with code examples →

Bundle size comparison

Method	Bundle Size	Tree-shaking	Loading	Use Case
Named imports (3 flags)	~2.8 KB	✅ Excellent	Instant	Known flags at build time
Named imports (10 flags)	~9.5 KB	✅ Excellent	Instant	Common flags header
CircleFlag	~2 KB	✅ Perfect	Async CDN	Dynamic flags, minimal bundle
DynamicFlag	~600 KB	❌ None	Instant	CDN-restricted, all flags needed

Expected bundle sizes

Size Reference (v1.4.0)

• Each flag component (named import): ~950 bytes (minified)
• CircleFlag component: ~2 KB (minified)
• DynamicFlag (includes all flags): ~600 KB (minified)
• 10 named imports: ~9.5 KB total (minified)

Performance tips

Code Splitting

Split flag components across routes to load only what’s needed per page.

Lazy Loading

Use React’s lazy() to defer loading flags until they’re actually rendered.

Static Analysis

Run bundle analysis regularly to catch unexpected size increases.

Use CircleFlag

For dynamic flags, prefer CircleFlag over DynamicFlag to avoid bundling unused flags.

Hybrid approach: Best of both worlds

Combine named imports for known flags with CircleFlag for dynamic ones:

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

export function Header({ userCountry }: { userCountry?: string }) {
  return (
    <div className="flex gap-2">
      {/* Static flags: bundled (~950 bytes) */}
      <FlagUs width={32} height={32} />

      {/* Dynamic flag: loaded from CDN (~0 KB) */}
      {userCountry && <CircleFlag countryCode={userCountry} width={32} height={32} />}
    </div>
  )
}

Total bundle impact: ~2.9 KB (FlagUs + CircleFlag component)

Analyzing your bundle

Use these tools to verify your bundle size:

# Webpack Bundle Analyzer
npm install --save-dev webpack-bundle-analyzer

# Vite Bundle Analyzer
npm install --save-dev rollup-plugin-visualizer

# Next.js Bundle Analyzer
npm install --save-dev @next/bundle-analyzer

Related

Basic Usage Learn how to import and use flag components with code examples

Dynamic Flags Deep dive into CircleFlag and DynamicFlag components