### Install and Run Development Server

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/examples/example-vue/README.md

Install project dependencies and start the development server from the repository root.

```bash
npm install
npm run dev
```

--------------------------------

### Install @sankyu/vue-circle-flags

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/packages/vue/README.md

Install the library using npm, pnpm, yarn, or bun.

```bash
npm install @sankyu/vue-circle-flags
# or
pnpm add @sankyu/vue-circle-flags
# or
yarn add @sankyu/vue-circle-flags
# or
bun add @sankyu/vue-circle-flags
```

--------------------------------

### Install Dependencies

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/README.md

Installs all necessary project dependencies using pnpm.

```bash
pnpm install
```

--------------------------------

### Install Website Dependencies

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/README.md

Installs the necessary dependencies for the website using pnpm. Ensure you are in the website directory.

```bash
cd website
pnpm install
```

--------------------------------

### Install Solid Circle Flags

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/packages/solid/README.md

Install the library using npm, pnpm, yarn, or bun.

```bash
npm install @sankyu/solid-circle-flags
# or
pnpm add @sankyu/solid-circle-flags
# or
yarn add @sankyu/solid-circle-flags
# or
bun add @sankyu/solid-circle-flags
```

--------------------------------

### Install React Circle Flags with bun

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/getting-started/installation.mdx

Use this command to install the React Circle Flags package with bun. Ensure React is already installed in your project.

```bash
bun add @sankyu/react-circle-flags
```

--------------------------------

### Install Solid.js Circle Flags with bun

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/getting-started/installation.mdx

Use this command to install the Solid.js Circle Flags package with bun. This is a beta release, and solid-js must be installed in your project.

```bash
bun add @sankyu/solid-circle-flags
```

--------------------------------

### Start Development Server

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/README.md

Launches the development server for the website, typically accessible at http://localhost:4321.

```bash
# Start development server at http://localhost:4321
pnpm dev
```

--------------------------------

### Install React Circle Flags with yarn

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/getting-started/installation.mdx

Use this command to install the React Circle Flags package with yarn. Ensure React is already installed in your project.

```bash
yarn add @sankyu/react-circle-flags
```

--------------------------------

### Install Solid.js Circle Flags with npm

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/getting-started/installation.mdx

Use this command to install the Solid.js Circle Flags package with npm. This is a beta release, and solid-js must be installed in your project.

```bash
npm install @sankyu/solid-circle-flags
```

--------------------------------

### Install Next.js Bundle Analyzer

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/getting-started/bundle-size.mdx

Install the Next.js Bundle Analyzer tool to analyze your bundle size with Next.js.

```bash
npm install --save-dev @next/bundle-analyzer
```

--------------------------------

### Install Solid.js Circle Flags with yarn

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/getting-started/installation.mdx

Use this command to install the Solid.js Circle Flags package with yarn. This is a beta release, and solid-js must be installed in your project.

```bash
yarn add @sankyu/solid-circle-flags
```

--------------------------------

### Install React Circle Flags with npm

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/getting-started/installation.mdx

Use this command to install the React Circle Flags package with npm. Ensure React is already installed in your project.

```bash
npm install @sankyu/react-circle-flags
```

--------------------------------

### Install React Circle Flags with pnpm

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/getting-started/installation.mdx

Use this command to install the React Circle Flags package with pnpm. Ensure React is already installed in your project.

```bash
pnpm add @sankyu/react-circle-flags
```

--------------------------------

### Install Vite Bundle Analyzer

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/getting-started/bundle-size.mdx

Install the Vite Bundle Analyzer tool to analyze your bundle size with Vite.

```bash
npm install --save-dev rollup-plugin-visualizer
```

--------------------------------

### Install Solid.js Circle Flags with pnpm

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/getting-started/installation.mdx

Use this command to install the Solid.js Circle Flags package with pnpm. This is a beta release, and solid-js must be installed in your project.

```bash
pnpm add @sankyu/solid-circle-flags
```

--------------------------------

### Install @sankyu/react-circle-flags using npm, pnpm, or yarn

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/migration/from-react-circle-flags.mdx

Follow these commands to uninstall the old package and install the new one. Choose the package manager you are currently using.

```bash
npm uninstall react-circle-flags
npm install @sankyu/react-circle-flags
```

```bash
pnpm remove react-circle-flags
pnpm add @sankyu/react-circle-flags
```

```bash
yarn remove react-circle-flags
yarn add @sankyu/react-circle-flags
```

--------------------------------

### Install Webpack Bundle Analyzer

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/getting-started/bundle-size.mdx

Install the Webpack Bundle Analyzer tool to analyze your bundle size with Webpack.

```bash
npm install --save-dev webpack-bundle-analyzer
```

--------------------------------

### Install Circle Flags UI Packages

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/README.md

Install the appropriate package for your framework (React, Vue, or Solid.js) using pnpm.

```bash
# React
pnpm add @sankyu/react-circle-flags

# Vue 3
pnpm add @sankyu/vue-circle-flags

# Solid.js
pnpm add @sankyu/solid-circle-flags
```

--------------------------------

### Install @sankyu/react-circle-flags

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/packages/react/README.md

Install the library using npm, pnpm, yarn, or bun. This command adds the package to your project's dependencies.

```bash
npm install @sankyu/react-circle-flags
# or
pnpm add @sankyu/react-circle-flags
# or
yarn add @sankyu/react-circle-flags
# or
bun add @sankyu/react-circle-flags
```

--------------------------------

### Install Vue 3 Circle Flags with bun

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/getting-started/installation.mdx

Use this command to install the Vue 3 Circle Flags package with bun. This is a beta release, and Vue 3 must be installed in your project.

```bash
bun add @sankyu/vue-circle-flags
```

--------------------------------

### Valid Conventional Commit Examples

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/packages/solid/CONTRIBUTING.md

Examples of correctly formatted commit messages adhering to the Conventional Commits standard.

```bash
git commit -m "feat(flags): add 428 circular country flag components"
```

```bash
git commit -m "fix(build): resolve missing @eslint/js dependency"
```

```bash
git commit -m "docs: update installation instructions"
```

--------------------------------

### Install Vue 3 Circle Flags with yarn

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/getting-started/installation.mdx

Use this command to install the Vue 3 Circle Flags package with yarn. This is a beta release, and Vue 3 must be installed in your project.

```bash
yarn add @sankyu/vue-circle-flags
```

--------------------------------

### Install Vue 3 Circle Flags with npm

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/getting-started/installation.mdx

Use this command to install the Vue 3 Circle Flags package with npm. This is a beta release, and Vue 3 must be installed in your project.

```bash
npm install @sankyu/vue-circle-flags
```

--------------------------------

### Build All Packages

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/README.md

Builds all packages within the monorepo. Ensure dependencies are installed and flags are generated before running this command.

```bash
pnpm run build
```

--------------------------------

### Solid.js Flag Component Typing

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/getting-started/typescript.mdx

Provides advanced typing examples for Solid.js, demonstrating how to infer props for flag components using Parameters and defining reusable wrapper components.

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

--------------------------------

### Install Vue 3 Circle Flags with pnpm

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/getting-started/installation.mdx

Use this command to install the Vue 3 Circle Flags package with pnpm. This is a beta release, and Vue 3 must be installed in your project.

```bash
pnpm add @sankyu/vue-circle-flags
```

--------------------------------

### Quick Start with esm.sh CDN

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/advanced/cdn-usage.mdx

This HTML snippet demonstrates how to load React and the Circle Flags component from esm.sh. It includes an import map for resolving React dependencies and a script to render a US flag.

```html
<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <script type="importmap">
      {
        "imports": {
          "react": "https://esm.sh/react@19",
          "react-dom/client": "https://esm.sh/react-dom@19/client",
          "react/jsx-runtime": "https://esm.sh/react@19/jsx-runtime"
        }
      }
    </script>
  </head>
  <body>
    <div id="root"></div>

    <script type="module">
      import { createRoot } from 'react-dom/client'
      import { FlagUs } from 'https://esm.sh/@sankyu/react-circle-flags@1.6.2?exports=FlagUs'

      function App() {
        return <FlagUs width={64} height={64} title="US" />
      }

      createRoot(document.getElementById('root')).render(<App />)
    </script>
  </body>
</html>
```

--------------------------------

### Invalid Conventional Commit Examples

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/packages/solid/CONTRIBUTING.md

Examples of commit messages that do not follow the Conventional Commits standard, highlighting common mistakes.

```bash
git commit -m "添加国旗组件"  # Not English
```

```bash
git commit -m "Add flags"  # Missing type
```

```bash
git commit -m "feat: Add new feature."  # Period at end
```

```bash
git commit -m "FEAT: NEW FEATURE"  # Not lowercase
```

--------------------------------

### Available Flags

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/packages/solid/README.md

Lists the naming convention for individual flag components and provides examples of common flags.

```APIDOC
## Available Flags

### Description

Each flag is exported as a component following the pattern `Flag{PascalCase ISO_CODE}`. Convenience aliases are provided for commonly used two-letter ISO codes.

### Naming Convention

- **Pattern**: `Flag{PascalCase ISO_CODE}` (e.g., `FlagUs`, `FlagCn`)
- **Convenience Aliases**: `FlagUs`, `FlagCn`, `FlagGb`, `FlagJp`

### Examples

- `FlagUs` - United States
- `FlagCn` - China
- `FlagGb` - United Kingdom
- `FlagJp` - Japan

For a comprehensive list, refer to the [Full list of flags](https://react-circle-flags.js.org/browse) in the gallery.
```

--------------------------------

### Handle Runtime Country Codes with CDN Imports

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/advanced/cdn-usage.mdx

This JavaScript example demonstrates how to map runtime country codes to specific flag components imported from a CDN. It ensures that only the required flags are loaded and provides a fallback for unknown codes.

```javascript
import {
  FlagCn,
  FlagGb,
  FlagUs,
} from 'https://esm.sh/@sankyu/react-circle-flags@1.6.2?exports=FlagCn,FlagGb,FlagUs'

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

export function CountryFlag({ code }) {
  const normalized = String(code).toLowerCase()
  const Flag = FLAGS[normalized]
  return Flag ? <Flag width={36} height={36} /> : <span>{String(code).toUpperCase()}</span>
}
```

--------------------------------

### Solid.js: TypeScript Types and Helpers

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/getting-started/typescript.mdx

Provides examples of using `FlagCode`, `CountryCode`, and `FlagComponentProps` types in Solid.js with TypeScript. Demonstrates the functionality of `coerceFlagCode` and `isFlagCode` for ensuring type safety and handling flag codes.

```typescript
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')
```

--------------------------------

### React: TypeScript Types and Helpers

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/getting-started/typescript.mdx

Demonstrates the usage of `FlagCode`, `CountryCode`, and `FlagComponentProps` types in React. Includes examples of runtime helpers like `coerceFlagCode` and `isFlagCode` for data validation and normalization.

```tsx
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)
```

--------------------------------

### Style Flags in Vue 3

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/getting-started/styling.mdx

Demonstrates styling flags in Vue 3 using class bindings, inline styles, and scoped CSS. This example shows how to apply different styling methods within a Vue component.

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

<template>
  <!-- Using class -->
  <FlagUs class="w-12 h-12 rounded-full shadow-lg hover:scale-110 transition-transform" />

  <!-- Using inline styles -->
  <FlagUs :style="{ width: '48px', height: '48px', borderRadius: '50%' }" />

  <!-- With scoped styles -->
  <FlagUs class="flag" />
</template>

<style scoped>
.flag {
  width: 3rem;
  height: 3rem;
  border-radius: 50%;
  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
  transition: transform 0.2s;
}

.flag:hover {
  transform: scale(1.1);
}
</style>
```

--------------------------------

### Responsive Flag Sizes (React)

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/advanced/flag-utils.mdx

Dynamically adjust flag sizes based on window width in React using `FlagUtils.sizes`. This example sets up an effect to listen for window resize events.

```tsx
import { FlagUtils } from '@sankyu/react-circle-flags'
import { FlagUs } from '@sankyu/react-circle-flags'
import { useEffect, useState } from 'react'

export function ResponsiveFlag() {
  const [size, setSize] = useState(FlagUtils.sizes.md)

  useEffect(() => {
    const updateSize = () => {
      const width = window.innerWidth
      if (width < 640) return setSize(FlagUtils.sizes.sm)
      if (width < 1024) return setSize(FlagUtils.sizes.md)
      setSize(FlagUtils.sizes.lg)
    }

    updateSize()
    window.addEventListener('resize', updateSize)
    return () => window.removeEventListener('resize', updateSize)
  }, [])

  return <FlagUs width={size} height={size} />
}
```

--------------------------------

### Responsive Flag Sizes (Vue 3)

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/advanced/flag-utils.mdx

Dynamically adjust flag sizes based on window width in Vue 3 using `FlagUtils.sizes`. This example uses `onMounted` and `onUnmounted` to manage the resize event listener.

```vue
<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue'
import { FlagUtils } from '@sankyu/vue-circle-flags'
import { FlagUs } from '@sankyu/vue-circle-flags'

const size = ref(FlagUtils.sizes.md)

const updateSize = () => {
  const width = window.innerWidth
  if (width < 640) {
    size.value = FlagUtils.sizes.sm
    return
  }
  if (width < 1024) {
    size.value = FlagUtils.sizes.md
    return
  }
  size.value = FlagUtils.sizes.lg
}

onMounted(() => {
  updateSize()
  window.addEventListener('resize', updateSize)
})

onUnmounted(() => {
  window.removeEventListener('resize', updateSize)
})
</script>

<template>
  <FlagUs :width="size" :height="size" />
</template>
```

--------------------------------

### Build Parent Library and Website

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/README.md

Builds the parent library first, then builds the website. The website build output is placed in the dist/ directory.

```bash
# Build parent library first
cd ..
pnpm build

# Then build website
cd website
pnpm build
```

--------------------------------

### Preview Production Build

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/README.md

Serves a preview of the production build of the website.

```bash
pnpm preview
```

--------------------------------

### Common Commands for Development

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/examples/example-vue/README.md

Common commands for managing the development, building, and previewing of the Vue application.

```bash
# development
npm run dev

# type-check + production build
npm run build

# preview built app
npm run preview
```

--------------------------------

### Import from Parent Library Source

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/README.md

Demonstrates how to import components and constants directly from the parent library's source code using the configured TypeScript path mapping.

```typescript
import { FLAG_REGISTRY, FlagUs } from '@sankyu/react-circle-flags'
```

--------------------------------

### Access Build Meta Information

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/packages/react/README.md

Import the `buildMeta` export to access library build details like version, timestamps, and commit hashes. Useful for debugging or version tracking.

```tsx
import { buildMeta } from '@sankyu/react-circle-flags'

console.log(buildMeta.version) // e.g., "1.2.3"
console.log(buildMeta.builtTimestamp) // e.g., 1760000000000
console.log(buildMeta.commitHash) // e.g., <example-sha256-hash>
console.log(buildMeta.circleFlagsCommitHash) // e.g., <example-sha256-hash>
```

--------------------------------

### Flag Code Utilities

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/advanced/flag-utils.mdx

Utilities for validating, formatting, and getting component names for country codes.

```APIDOC
## `isValidCountryCode(code: string): boolean`

### Description
Check if a string is a valid country/subdivision code.

### Parameters
#### Path Parameters
- **code** (string) - Required - The country or subdivision code to validate.

### Response
#### Success Response (boolean)
- **true** if the code is valid, **false** otherwise.

### Example
```ts
FlagUtils.isValidCountryCode('us') // true
FlagUtils.isValidCountryCode('invalid') // false
```
```

```APIDOC
## `formatCountryCode(code: string): string`

### Description
Normalize a country code to uppercase display format.

### Parameters
#### Path Parameters
- **code** (string) - Required - The country code to format.

### Response
#### Success Response (string)
- The formatted country code in uppercase.

### Example
```ts
FlagUtils.formatCountryCode('us') // 'US'
FlagUtils.formatCountryCode('invalid') // 'INVALID'
```
```

```APIDOC
## `getComponentName(code: string): string`

### Description
Get the component name for a flag code (e.g., `FlagUs`).

### Parameters
#### Path Parameters
- **code** (string) - Required - The flag code to get the component name for.

### Response
#### Success Response (string)
- The component name for the flag.

### Example
```ts
FlagUtils.getComponentName('us') // 'FlagUs'
FlagUtils.getComponentName('gb-eng') // 'FlagGbEng'
```
```

--------------------------------

### Get Flag Component Name

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/advanced/flag-utils.mdx

Use `getComponentName` to retrieve the component name for a given flag code, such as `FlagUs`.

```ts
FlagUtils.getComponentName('us') // 'FlagUs'
FlagUtils.getComponentName('gb-eng') // 'FlagGbEng'
```

--------------------------------

### SolidStart Flag Usage

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/getting-started/usage.mdx

Import and render US and China flags in a SolidStart application. Ensure the '@sankyu/solid-circle-flags' package is installed.

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

--------------------------------

### Import FlagUtils for Solid.js

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/advanced/flag-utils.mdx

Import the FlagUtils class when using Solid.js.

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

--------------------------------

### Remix Flag Usage

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/getting-started/usage.mdx

Import and render US and China flags in a Remix application. Ensure the '@sankyu/react-circle-flags' package is installed.

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

--------------------------------

### Next.js Flag Usage

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/getting-started/usage.mdx

Import and render US and China flags in a Next.js application. Ensure the '@sankyu/react-circle-flags' package is installed.

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

--------------------------------

### Vue 3 Flag Usage

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/getting-started/usage.mdx

Import and render US and China flags in a Vue 3 application. Ensure the '@sankyu/vue-circle-flags' package is installed.

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

--------------------------------

### Version Property

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/reference/api/Interface.BuildMeta.md

Represents the version string of the build.

```typescript
version: string;
```

--------------------------------

### Size Presets

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/packages/solid/README.md

Provides a list of predefined size presets for flags, mapping size names to pixel values for easy application.

```APIDOC
## Size Presets

### Description

This section lists the available size presets that can be used for the `width` and `height` props of flag components, offering convenient predefined dimensions.

### Parameters

#### Size Presets

- **`xs`**: 16px
- **`sm`**: 24px
- **`md`**: 32px
- **`lg`**: 48px
- **`xl`**: 64px
- **`xxl`**: 96px
- **`xxxl`**: 128px
```

--------------------------------

### Nuxt.js Flag Usage

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/getting-started/usage.mdx

Import and render US and China flags in a Nuxt.js application using Vue. Ensure the '@sankyu/vue-circle-flags' package is installed.

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

--------------------------------

### Get Flag Component Name (React)

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/getting-started/typescript.mdx

Retrieve the component name for a flag using its country code with `FlagUtils.getComponentName`. This is useful for dynamic rendering.

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

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

--------------------------------

### AI Agent Prompts for Flag Optimization

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/packages/react/README.md

Prompts for AI agents to audit flag usage, propose migrations to the `@sankyu/{framework}-circle-flags` package, and optimize for tree-shaking using named imports.

```txt
Act as an expert Web Engineer. Reference: https://react-circle-flags.js.org/llms.txt & https://react-circle-flags.js.org/llms-small.txt

1. **Audit my project** to find any flag usage:
   - Raw `<img>` tags pointing to `HatScripts/circle-flags` URLs.
   - Legacy `react-circle-flags` library usage.
2. **Propose a migration** to the appropriate `@sankyu/{framework}-circle-flags` package based on my current framework (React/Vue/Solid).
3. **Optimize for Tree-shaking**: Replace generic `CircleFlag` components or raw tags with **named imports** (e.g., `import { Us } from '...'`) as per the docs.
```

--------------------------------

### AI Agent Prompt for Flag Migration

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/README.md

A prompt for AI agents to audit a project for existing flag usage, propose migration to the appropriate @sankyu/{framework}-circle-flags package, and optimize for tree-shaking by using named imports.

```txt
Act as an expert Web Engineer. Reference: https://react-circle-flags.js.org/llms.txt & https://react-circle-flags.js.org/llms-small.txt

1. Audit my project to find any flag usage:
   - Raw <img> tags pointing to HatScripts/circle-flags URLs.
   - Legacy react-circle-flags library usage.
2. Propose a migration to the appropriate @sankyu/{framework}-circle-flags package based on my framework (React/Vue/Solid).
3. Optimize for Tree-shaking: replace generic CircleFlag components with named imports (e.g. import { FlagUs } from '...') as per the docs.
```

--------------------------------

### Vite (Solid) Flag Usage

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/getting-started/usage.mdx

Import and render US and China flags in a Vite project using Solid. Ensure the '@sankyu/solid-circle-flags' package is installed.

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

--------------------------------

### Vite File System Access Configuration

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/README.md

Configures Vite within the Astro build process to allow file system access to the parent directory, necessary for importing from the parent library.

```javascript
vite: {
  server: {
    fs: {
      allow: ['..']
    }
  }
}
```

--------------------------------

### Vite (React) Flag Usage

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/getting-started/usage.mdx

Import and render US and China flags in a Vite project using React. Ensure the '@sankyu/react-circle-flags' package is installed.

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

--------------------------------

### Build Meta Information

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/packages/solid/README.md

Exposes build-time metadata for the library, including version, build timestamp, and commit hashes.

```APIDOC
## Build Meta Information

### Description

Access build meta information directly from the `buildMeta` export. This includes the library version, when it was built, and relevant commit hashes.

### Export

- **`buildMeta`**: An object containing build metadata.
  - **`version`** (string): The library version (e.g., "0.0.1").
  - **`builtTimestamp`** (number): The timestamp of the build (e.g., 1760000000000).
  - **`commitHash`** (string): The commit hash of the library build (e.g., "<example-sha256-hash>").
  - **`circleFlagsCommitHash`** (string): The commit hash of the underlying Circle Flags data (e.g., "<example-sha256-hash>").
```

--------------------------------

### React DynamicFlag with TypeScript

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/getting-started/typescript.mdx

Example of using DynamicFlag in a React component with type-safe country codes. Ensure `strict` prop is used for type checking.

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

--------------------------------

### Handle Flag Sizes (React)

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/getting-started/typescript.mdx

Use `FlagUtils.getSizeName` to get the size identifier for a given pixel value, and access `FlagUtils.sizes` to see available size mappings.

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

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

--------------------------------

### Access Build Meta Information

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/packages/vue/README.md

Retrieve build metadata such as version, timestamps, and commit hashes from the `buildMeta` export.

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

console.log(buildMeta.version) // e.g., "0.0.1"
console.log(buildMeta.builtTimestamp) // e.g., 1760000000000
console.log(buildMeta.commitHash) // e.g., <example-sha256-hash>
console.log(buildMeta.circleFlagsCommitHash) // e.g., <example-sha256-hash>
</script>
```

--------------------------------

### Predefined Flag Size Constants

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/advanced/flag-utils.mdx

Access the `sizes` object to get the pixel values for predefined flag sizes like `xs`, `sm`, `md`, etc.

```ts
FlagUtils.sizes.xs // 16
FlagUtils.sizes.sm // 24
FlagUtils.sizes.md // 32
FlagUtils.sizes.lg // 48
FlagUtils.sizes.xl // 64
FlagUtils.sizes.xxl // 96
FlagUtils.sizes.xxxl // 128
```

--------------------------------

### Style Flag in Solid.js

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/getting-started/styling.mdx

Style flags in Solid.js using `className` for CSS classes and the `style` prop for inline styles. This example also includes ARIA attributes for accessibility.

```tsx
import { FlagUs } from '@sankyu/solid-circle-flags'

export default function SolidFlag() {
  return (
    <FlagUs
      width={48}
      height={48}
      className="w-12 h-12 rounded-full shadow-lg hover:scale-110 transition-transform"
      style={{ filter: 'grayscale(100%)' }}
      aria-label="United States flag"
    />
  )
}
```

--------------------------------

### Tree-shaking with Individual Flag Imports

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/packages/vue/README.md

Shows the recommended way to import flags to ensure tree-shaking, where only the explicitly imported flags are included in the final bundle.

```vue
<script setup lang="ts">
// ✓ Good - only FlagUs and FlagCn are bundled
import { FlagUs, FlagCn } from '@sankyu/vue-circle-flags'
</script>
```

--------------------------------

### Size Utilities

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/advanced/flag-utils.mdx

Utilities for working with predefined flag sizes.

```APIDOC
## `getSizeName(pixels: number): FlagSizeName | null`

### Description
Get the predefined size name from a pixel value.

### Parameters
#### Path Parameters
- **pixels** (number) - Required - The size in pixels.

### Response
#### Success Response (FlagSizeName | null)
- The predefined size name (e.g., 'xs', 'sm') or null if no match is found.

### Example
```ts
FlagUtils.getSizeName(16) // 'xs'
FlagUtils.getSizeName(100) // null
```
```

```APIDOC
## `sizes: Record<FlagSizeName, number>`

### Description
An object containing predefined size constants mapping size names to pixel values.

### Properties
- **xs** (number) - The size in pixels for extra small.
- **sm** (number) - The size in pixels for small.
- **md** (number) - The size in pixels for medium.
- **lg** (number) - The size in pixels for large.
- **xl** (number) - The size in pixels for extra large.
- **xxl** (number) - The size in pixels for double extra large.
- **xxxl** (number) - The size in pixels for triple extra large.

### Example
```ts
FlagUtils.sizes.xs // 16
FlagUtils.sizes.md // 32
```
```

--------------------------------

### Convert Country Code to Component Name (Vue 3)

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/getting-started/typescript.mdx

Use `FlagUtils.getComponentName` in Vue 3 projects to get the PascalCase name for a flag component based on its country code.

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

FlagUtils.getComponentName('us') // 'FlagUs'
```

--------------------------------

### Get Component Name Dynamically (React)

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/advanced/flag-utils.mdx

Retrieve the component name for a given country code using `FlagUtils.getComponentName` in React. This snippet also shows how to check for code validity.

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

export function FlagInfo({ code }: { code: string }) {
  const componentName = FlagUtils.getComponentName(code)
  const isValid = FlagUtils.isValidCountryCode(code)

  return (
    <div>
      <p>Country Code: {code.toUpperCase()}</p>
      <p>Component: {componentName}</p>
      <p>Status: {isValid ? 'Valid' : 'Invalid'}</p>
    </div>
  )
}
```

--------------------------------

### Use FlagSizes Presets

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/packages/vue/README.md

Utilize predefined size presets like 'sm', 'md', and 'lg' for consistent flag sizing across your application.

```vue
<script setup lang="ts">
import { FlagJp, FlagDe, FlagFr, FlagSizes } from '@sankyu/vue-circle-flags'
</script>

<template>
  <div>
    <FlagJp :width="FlagSizes.sm" :height="FlagSizes.sm" />
    <!-- 24px -->
    <FlagDe :width="FlagSizes.md" :height="FlagSizes.md" />
    <!-- 32px -->
    <FlagFr :width="FlagSizes.lg" :height="FlagSizes.lg" />
    <!-- 48px -->
  </div>
</template>
```

--------------------------------

### Import Individual Flags

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/packages/solid/README.md

Import and use specific flags directly by their PascalCase ISO code. This is the recommended approach for performance and tree-shaking.

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

export default function App() {
  return (
    <div>
      <FlagUs width={48} height={48} />
      <FlagCn width={48} height={48} />
      <FlagGb width={48} height={48} />
    </div>
  )
}
```

--------------------------------

### Get Flag Size Name from Pixels

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/advanced/flag-utils.mdx

Use `getSizeName` to map a pixel value to a predefined flag size name. Returns `null` if the pixel value does not match any predefined size.

```ts
FlagUtils.getSizeName(16) // 'xs'
FlagUtils.getSizeName(24) // 'sm'
FlagUtils.getSizeName(32) // 'md'
FlagUtils.getSizeName(48) // 'lg'
FlagUtils.getSizeName(64) // 'xl'
FlagUtils.getSizeName(96) // 'xxl'
FlagUtils.getSizeName(128) // 'xxxl'
FlagUtils.getSizeName(100) // null
```

--------------------------------

### Handle Flag Sizes (Vue 3)

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/getting-started/typescript.mdx

Vue 3's `FlagUtils` allows getting size names from pixel values using `getSizeName` and accessing predefined sizes via `FlagUtils.sizes`.

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

FlagUtils.getSizeName(48)             // "lg"
FlagUtils.sizes.lg                    // 48
```

--------------------------------

### Import Type Utilities in Solid.js

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/advanced/type-utilities.mdx

Import the necessary type utilities and the `FlagCode` type for Solid.js applications.

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

--------------------------------

### Get Component Name Dynamically (Vue 3)

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/advanced/flag-utils.mdx

Retrieve the component name for a given country code using `FlagUtils.getComponentName` in Vue 3. This snippet uses computed properties for reactive updates.

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

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

const componentName = computed(() => FlagUtils.getComponentName(props.code))
const isValid = computed(() => FlagUtils.isValidCountryCode(props.code))
</script>

<template>
  <div>
    <p>Country Code: {{ props.code.toUpperCase() }}</p>
    <p>Component: {{ componentName }}</p>
    <p>Status: {{ isValid ? 'Valid' : 'Invalid' }}</p>
  </div>
</template>
```

--------------------------------

### Solid.js DynamicFlag with TypeScript

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/getting-started/typescript.mdx

Shows how to implement DynamicFlag in a Solid.js component, leveraging TypeScript for type-safe country code handling.

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

--------------------------------

### BuildMeta Interface

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/reference/api/Interface.BuildMeta.md

The BuildMeta interface exposes properties related to the build process.

```APIDOC
## Interface: BuildMeta

### Description
This interface contains metadata about the build process.

### Properties

- **version** (string) - The version of the build.
- **commitHash** (string) - The Git commit hash of the build.
- **circleFlagsCommitHash** (string) - The Git commit hash specific to the circle-flags library used in the build.
- **builtTimestamp** (number) - The Unix timestamp indicating when the build was completed.
```

--------------------------------

### Handle Flag Sizes (Solid.js)

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/getting-started/typescript.mdx

Solid.js applications can use `FlagUtils.getSizeName` to map pixel values to size identifiers and access available sizes through `FlagUtils.sizes`.

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

FlagUtils.getSizeName(48)             // "lg"
FlagUtils.sizes.lg                    // 48
```

--------------------------------

### Version Pinning for Production CDN Usage

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/advanced/cdn-usage.mdx

This code snippet illustrates the difference between using a CDN without a version and with a specific version pinned. Pinning versions is a best practice for production to prevent unexpected breaking changes from CDN updates.

```diff
- import { FlagUs } from 'https://esm.sh/@sankyu/react-circle-flags?exports=FlagUs'
+ import { FlagUs } from 'https://esm.sh/@sankyu/react-circle-flags@1.6.2?exports=FlagUs'
```

--------------------------------

### Import Individual Flags

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/packages/vue/README.md

Import and use specific flag components directly. This is the recommended approach for better tree-shaking and performance.

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

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

--------------------------------

### Import Specific Exports from CDN

Source: https://github.com/sankyu-lab/circle-flags-ui/blob/main/website/src/content/docs/docs/guides/advanced/cdn-usage.mdx

This JavaScript snippet shows how to import only the necessary flag components from the CDN using the 'exports' query parameter to optimize bundle size.

```javascript
import {
  FlagCn,
  FlagUs,
} from 'https://esm.sh/@sankyu/react-circle-flags@1.6.2?exports=FlagCn,FlagUs'
```