Skip to main content

Flag

Displays a flag as an SVG for the country code you pass. The code prop takes an ISO 3166-1 alpha-2 country code, such as US.

When to use

  • Show the country of a region, an IP address, a billing address, or a locale.
  • Give a select option, a list row, or a status pill a quick visual cue.

When not to use

  • As a stand-in for language. Flags are not languages: Brazilian Portuguese is not "Portugal", and 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

The SVG loads from ngrok's CDN. Flag defaults to loading="lazy". Use loading="eager" for flags above the fold or in critical content.

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.