Skip to main content
/mantle

Flag

Renders a country flag from an ISO 3166-1 alpha-2 country code, served as an SVG from ngrok's CDN.

When to use

  • Showing the country associated with a region, IP, billing address, or locale.
  • Inside a select option, list row, or status pill that needs a quick visual cue.

When not to use

  • As a stand-in for language. Flags are not languages — Brazilian Portuguese is not "Portugal", Spanish is not just "Spain". Use a language label instead.
  • As decoration where the country isn't meaningful to the user.

Sizing

"s" (16×12), "m" (20×15), and "l" (32×24, default) match common inline, list, and table contexts. Pick the size that matches its neighbors so the flag doesn't dominate or disappear.

Accessibility

The underlying <img> is given alt="flag for {code}". If the country is decorative or already labeled in adjacent text, consider passing aria-hidden via the wrapper <div> to avoid duplicate announcements.

Loading

Defaults to loading="lazy". Use loading="eager" for flags above the fold or in critical content.

flag for US
flag for JP
flag for ES
import { Flag } from "@ngrok/mantle/flag"; <Flag code="US" /><Flag code="JP" loading="lazy" /><Flag code="ES" loading="eager" />

API Reference

The Flag accepts the following props in addition to the standard HTML div attributes.

PropTypeDefaultDescription
codeCountryCodeThe country code of the flag to render: an ISO 3166-1 alpha-2 code ("US"), alpha-3 code ("USA"), or numeric code ("840"). A string that is not in the union is a type error.
size"s" | "m" | "l""l"The size of the flag to render. The default size is large.
loading"eager" | "lazy""lazy"A string providing a hint to the user agent as to how to best schedule the loading of the image to optimize page performance. See MDN docs.

Country codes

@ngrok/mantle/flag also exports the code list and its type guard.

ExportTypeDescription
countryCodesreadonly CountryCode[]Every code Flag accepts, from the flagpack index.
isCountryCode(value: unknown) => value is CountryCodeType guard that narrows an unknown value, such as an API response, to a CountryCode.
CountryCodetypeThe union of every accepted code.