pennants/react

React components. import { Pennant, PennantSvg } from 'pennants/react'.

Interfaces

PennantBox

CSS box of a pennant, as returned by pennantBox.

Properties

Property	Type	Description
height	string	CSS height: "<n>px" for numbers, the given length for strings, "1em" by default.
width	string	CSS width, derived from the height with the shape's ratio ("29.333px", "calc(2rem * 66 / 72)").

---

PennantCommonProps

Props shared by Pennant and PennantSvg.

Extended by

• PennantProps
• PennantSvgProps

Properties

Property	Type	Description
locale?	string	Locale used for the default title (via Intl.DisplayNames). Default en.
shape?	"pennant" | "rect" | "square" | "circle"	Flag shape: pennant (default), rect (4:3), square or circle.
size?	PennantSize	Height (px number or CSS length). Width follows the 66:72 ratio. Default 1em.
title?	string	Accessible name. Defaults to the localised flag name. Pass "" to mark the pennant as decorative (aria-hidden, empty alt).

---

PennantProps

Props of Pennant. Other HTML attributes and ref are forwarded.

Extends

• PennantHtmlAttributes
• PennantCommonProps

Properties

Property	Type	Description	Inherited from
base?	string	fetch/img modes: where the package's svg/ folder is served. Default: versioned jsDelivr CDN.	-
code	PennantCode | Uppercase<PennantCode>	Flag code, lowercase or uppercase ("ar", "AR", "gb-eng", "GB-ENG"); normalised with toPennantCode. Unknown codes throw a RangeError.	-
decoding?	"auto" | "async" | "sync"	img mode: image decoding hint. Default async.	-
loading?	"lazy" | "eager"	img mode: native lazy loading. Default lazy.	-
locale?	string	Locale used for the default title (via Intl.DisplayNames). Default en.	PennantCommonProps.locale
mode?	"img" | "inline" | "fetch"	- inline (default): lazy-loads the flag's bundled artwork chunk and inlines the SVG; - fetch: fetches <base>/svg/<shape>/<code>.svg at runtime and inlines it (no bundled flag data at all); - img: renders an <img> pointing at <base>/svg/<shape>/<code>.svg.	-
shape?	"pennant" | "rect" | "square" | "circle"	Flag shape: pennant (default), rect (4:3), square or circle.	PennantCommonProps.shape
size?	PennantSize	Height (px number or CSS length). Width follows the 66:72 ratio. Default 1em.	PennantCommonProps.size
title?	string	Accessible name. Defaults to the localised flag name. Pass "" to mark the pennant as decorative (aria-hidden, empty alt).	PennantCommonProps.title

---

PennantSvgProps

Props of PennantSvg: shared props plus statically imported artwork.

Extends

• PennantHtmlAttributes
• PennantCommonProps

Properties

Property	Type	Description	Inherited from
art	FlagArt	Flag artwork, e.g. import ar from 'pennants/art/1x1/ar'. Use the 4x3 set for shape="rect" and 1x1 for the other shapes. Must be trusted.	-
locale?	string	Locale used for the default title (via Intl.DisplayNames). Default en.	PennantCommonProps.locale
shape?	"pennant" | "rect" | "square" | "circle"	Flag shape: pennant (default), rect (4:3), square or circle.	PennantCommonProps.shape
size?	PennantSize	Height (px number or CSS length). Width follows the 66:72 ratio. Default 1em.	PennantCommonProps.size
title?	string	Accessible name. Defaults to the localised flag name. Pass "" to mark the pennant as decorative (aria-hidden, empty alt).	PennantCommonProps.title

Type Aliases

PennantHtmlAttributes

type PennantHtmlAttributes = Omit<HTMLAttributes<HTMLElement>, "title" | "children" | "dangerouslySetInnerHTML">;

HTML attributes forwarded to the rendered element (title/children/inner HTML are managed).

---

PennantSize

type PennantSize = number | string;

Pennant height: a number of CSS pixels or any CSS length ("2rem").

Variables

Pennant

const Pennant: ForwardRefExoticComponent<PennantProps & RefAttributes<HTMLElement>>;

Renders a flag (any shape) on the client. Unknown codes or shapes throw a RangeError. Inline/fetch modes keep the box reserved while loading; img mode points at the static SVG asset.

---

PennantSvg

const PennantSvg: ForwardRefExoticComponent<PennantSvgProps & RefAttributes<HTMLSpanElement>>;

Synchronous flag from statically imported artwork: import ar from 'pennants/art/1x1/ar' then <PennantSvg art={ar} shape="circle" />. Uses only useId/useMemo, so it also renders in React Server Components. Throws a RangeError for unknown shapes.

Functions

pennantBox()

function pennantBox(size?, shape?): PennantBox;

Box size for a given size prop: explicit height, width derived from the shape's aspect ratio (66:72 pennant, 4:3 rect, 1:1 square/circle). Handy to reserve space for a flag outside the components.

Parameters

Parameter	Type	Default value
size?	PennantSize	undefined
shape?	"pennant" | "rect" | "square" | "circle"	'pennant'

Returns

PennantBox