Flags

Flags#

Every country, the territories that fly their own flag, and a few regions such as the European Union, Scotland and Catalonia, sorted by name. Search by name or by code, pick a shape, then hover a flag and use Copy SVG to paste it into Figma, or Download SVG for a standalone file in that shape.

Installation#

# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add flag

Shapes#

One set of 3:2 art, cropped three ways. rectangle shows the whole flag; square and circle cover the box from the centre, so the color always reaches the edge. A 1px hairline sits over the art so white flags like Japan’s keep their edge on a white surface.

Sizes#

size sets the height and the shape sets the width, so a rectangle and a circle of the same size share a line. The corners grow with the flag and follow the radius knob.

In context#

A flag leads a row and the name beside it carries the meaning, which is why the flag is decorative by default. CountrySelect, PhoneInput and JobCard use this same round crop.

Usage#

Pass an ISO 3166-1 alpha-2 code (ES), or an ISO 3166-2 code for a region with its own flag (GB-SCT). The same codes key the FLAGS list, so names come along. Give the flag a label when it stands alone, as in a language switcher that shows only flags.

import { Flag, FLAGS, FLAG_BY_CODE } from "@/components/ui/flag"

// Rectangle by default, 20px tall
<Flag code="ES" />

// Round, beside its name
<Flag code="JP" shape="circle" size="sm" />
<span>{FLAG_BY_CODE.JP.name}</span>

// Standing alone: give it a name
<Flag code="FR" shape="square" label="Français" />

// Every flag, sorted by name
{FLAGS.map((flag) => (
  <Flag key={flag.code} code={flag.code} shape="circle" />
))}

The artwork is country-flag-icons, MIT licensed. Because Flag resolves any code, the whole set ships wherever it renders on the client, as it already does for CountrySelect and PhoneInput. It holds no state, so in a Server Component the art renders on the server and none of it reaches the browser.