pennantsEvery flag, every shape, one API

271 country flags as pennants (the signature style), rectangles, squares and circles. SVG, PNG, CSS, sprite, tree-shakable JS, React and a Web Component; you only ship the flags you show.

Get started

Browse the gallery

Shapes

Which format?

Four shapes

Pennant by default, plus 4:3 rectangle, square and circle. Same codes, same API; pick the shape with one option.

Every format

Static SVG and PNG, CSS classes, an SVG sprite, one ES module per flag, a React component and a framework-free custom element.

Pay only for what you show

Each flag is its own module and lazy chunk, so you ship only the flags you show. Names come from Intl.DisplayNames, so no name data ships.

Typed and localized

A PennantCode union for all 271 codes, and names in any language through Intl.DisplayNames, with no bundled name data.

Accessible by default

Components get a localized accessible name automatically; pass an empty title or label for decorative flags.

Themeable

Recolor the pennant's hanging bar with two CSS custom properties. CSP-safe.

Same codes as flag-icons

Built from the flag-icons artwork. Keep rectangles with the rect shape, or switch to pennants.

Quick start

npm install pennants

import 'pennants/css';

html

<span class="pn pn-ar" role="img" aria-label="Argentina"></span>

Pick a format

CSS

import 'pennants/css';

<span class="pn pn-ar" role="img" aria-label="Argentina"></span>

One stylesheet per shape, combinable on one page, no JavaScript; each image loads only when its class is used. With Vite, use the cdn variant or set assetsInlineLimit (see FAQ).

Not sure? Read Which format should I use? or see every flag in the gallery.