Country flags and custom artwork

Flags for any occasion

Use preset="bunting" with a country flag to hang flags without fireworks, sparkles or an occasion-specific composition. The flag option accepts English slugs such as pakistan or japan and case-insensitive two-letter codes such as PK or JP.

import { Zeenat } from "zeenat";

<Zeenat preset="bunting" flag="pakistan" />;
<Zeenat preset="bunting" flag="JP" orientation="vertical" />;

Vanilla JavaScript

The framework-neutral API uses the same flag and orientation options. Destroy the decoration when its hosting view is removed.

import { zeenat } from "zeenat/vanilla";

const decoration = zeenat({
  preset: "bunting",
  flag: "pakistan",
  orientation: "vertical",
});

// When the view is removed:
decoration.destroy();

The packaged country catalog

flagCatalog contains 249 country and territory entries, each with code, name and slug. The catalog excludes IL and includes XK. Use these entries as the source for a country picker; unsupported names and codes are rejected.

resolveFlag resolves a supported name or code to metadata. countryFlag returns a reusable design synchronously, without browser globals; its optional geometry is loaded only when mounted. The playground's country selector uses this same catalog.

import { flagCatalog, resolveFlag, countryFlag } from "zeenat/flags";

const countries = flagCatalog; // { code, name, slug }[]
const japan = resolveFlag("JP");
const japanArtwork = countryFlag("japan");

Horizontal and vertical flags

Horizontal is the default. Vertical rotates the complete artwork 90° clockwise without stretching it; country-specific ceremonial vertical variants are not represented. Items remain tangent to the curved cord and keep their proportions when the viewport resizes.

The simple API supports orientation on bunting, pakistan-independence-day, pakistan-defence-day and us-independence-day. Their typed factories expose orientation too. Set flag only on the generic bunting preset.

import { createBuntingPreset } from "zeenat/presets/bunting";
import { createPakistanIndependenceDayPreset } from "zeenat/presets/pakistan-independence-day";

const japan = createBuntingPreset({ flag: "JP", orientation: "vertical" });
const independenceDay = createPakistanIndependenceDayPreset({
  orientation: "vertical",
});

Reusable designs and mixed flags

pakistanFlag and unitedStatesFlag are original reusable designs exported by zeenat/effects/bunting. Pass one or more designs through flags to repeat them along a cord. Use countryFlag for any supported catalog entry.

BuntingOptions is a union: flag mode takes flags and optional orientation; classic pennant mode takes colors and optional shape. Do not combine flags with colors or shape. Both modes support count, position, height, cableColor, layer and order.

import { bunting, pakistanFlag, unitedStatesFlag } from "zeenat/effects/bunting";
import { countryFlag } from "zeenat/flags";

const international = bunting({
  flags: [pakistanFlag, unitedStatesFlag, countryFlag("JP")],
  orientation: "horizontal",
  count: 12,
});

const classic = bunting({
  colors: ["#01411c", "#ffffff"],
  shape: "swallowtail",
});

Custom flag artwork contracts

Import BuntingFlagDesign and BuntingFlagRenderContext from zeenat/effects/bunting. A design provides a stable id, an aspectRatio and a render function. Artwork is drawn into a normalized SVG symbol once and reused by the flags on the cord.

Use the supplied document and container, keep SVG complexity bounded and prefix internal SVG IDs with container.id. The normalized viewBox is 0 0 width 1. If render awaits work, check signal.aborted before appending geometry. The owning effect aborts when removed, restarted or rebuilt across a breakpoint. Rejected renders mark the symbol as failed and are handled without an unhandled rejection.

interface BuntingFlagDesign {
  readonly id: string;
  readonly aspectRatio: number;
  render(context: BuntingFlagRenderContext): void | Promise<void>;
}

interface BuntingFlagRenderContext {
  readonly document: Document;
  readonly container: SVGSymbolElement;
  readonly width: number;
  readonly height: number;
  readonly signal: AbortSignal;
}

Local loading and artwork licensing

Country metadata ships with the package. Optional artwork geometry is split into on-demand ESM and CJS chunks, so selecting a country does not eagerly load every flag. Keep the complete generated dist directory when deploying. No remote image host or flag runtime dependency is required.

Pakistan and United States artwork is original CSS/SVG. Other artwork is adapted from the MIT-licensed country-flag-icons project. The package includes artwork licensing, and the source repository includes a reproducible development-only generator pinned to country-flag-icons@1.6.20.