pennants/element

Web Component. import { definePennantElement } from 'pennants/element', or import 'pennants/element/register' for <pennant-flag>.

Classes

PennantElement

<pennant-flag code="ar" size="32" label="Argentina"> — lazily loads the flag into its shadow root. Fires pennant-load / pennant-error. With a base attribute (or definePennantElement(tag, { base })) the flag is fetched from <base>/svg/<shape>/<code>.svg instead of the bundled chunks.

Extends

• Base

Constructors

Constructor

new PennantElement(): PennantElement;

Prefer document.createElement('pennant-flag') or the tag in HTML after definePennantElement().

Returns

PennantElement

Overrides

Base.constructor

Properties

Property	Modifier	Type	Default value	Description
defaultBase	static	string | undefined	undefined	Fetch base used when the element has no base attribute (set by definePennantElement).
observedAttributes	static readonly	readonly string[]	PROPS	Attributes the element reacts to: code, size, label, base, shape.

Accessors

base

Get Signature

get base(): string | null;

Fetch-mode base URL (see pennantUrl). Reflects the base attribute.

Returns

string | null

Set Signature

set base(value): void;

Sets the base attribute (fetch mode); null returns to the tag default.

Parameters

Parameter	Type
value	string | null

Returns

void

code

Get Signature

get code(): string | null;

Flag code (any casing). Reflects the code attribute.

Returns

string | null

Set Signature

set code(value): void;

Sets (or with null removes) the code attribute.

Parameters

Parameter	Type
value	string | null

Returns

void

label

Get Signature

get label(): string | null;

Accessible name; defaults to the English flag name, "" = decorative.

Returns

string | null

Set Signature

set label(value): void;

Sets the label attribute; "" marks it decorative, null restores the default name.

Parameters

Parameter	Type
value	string | null

Returns

void

shape

Get Signature

get shape(): "pennant" | "rect" | "square" | "circle" | null;

Flag shape: pennant (default), rect, square or circle. Reflects the shape attribute.

Returns

"pennant" | "rect" | "square" | "circle" | null

Set Signature

set shape(value): void;

Sets the shape attribute; null returns to pennant. Unknown shapes fire pennant-error.

Parameters

Parameter	Type
value	"pennant" | "rect" | "square" | "circle" | null

Returns

void

size

Get Signature

get size(): string | null;

Height: a number of px or any CSS length. Reflects the size attribute.

Returns

string | null

Set Signature

set size(value): void;

Sets the size attribute; numbers are pixels. null removes it.

Parameters

Parameter	Type
value	string | number | null

Returns

void

Interfaces

DefinePennantElementOptions

Options of definePennantElement.

Properties

Property	Type	Description
base?	string	Fetch mode for every instance of this tag: load <base>/svg/<shape>/<code>.svg with fetchPennant instead of the bundled flag chunks. A per-element base attribute takes precedence.

---

PennantErrorDetail

detail of the pennant-error event (unknown code, failed download or invalid fetched markup).

Properties

Property	Type	Description
code	string	The code attribute value that failed.
error	unknown	The rejection reason: a RangeError for unknown codes, otherwise the load/fetch error.

---

PennantLoadDetail

detail of the pennant-load event, fired once the flag is rendered.

Properties

Property	Type	Description
code	PennantCode	Normalised code of the flag that was loaded.

Variables

PENNANT_ELEMENT_CSS

const PENNANT_ELEMENT_CSS: string;

Shadow styles. Includes the bar theming rule: document styles don't reach the shadow root, but custom properties inherit, so --pennant-bar-light / --pennant-bar-dark on any ancestor recolour the bar.

Functions

definePennantElement()

function definePennantElement(tagName?, options?): typeof PennantElement | undefined;

Registers the element (default tag pennant-flag). Idempotent: returns the already-registered constructor if the tag exists (options are then ignored). No-op (returns undefined) where customElements is unavailable, e.g. during SSR. { base } switches the tag to fetch mode.

Parameters

Parameter	Type	Default value
tagName?	string	'pennant-flag'
options?	DefinePennantElementOptions	{}

Returns

typeof PennantElement | undefined