CountryFlag component

Accessibility

The CountryFlag component has been designed with accessibility in mind, providing flexible options for screen reader support depending on the context in which the flag is used.

Accessibility Props

CountryFlag props:

Name	Type	Description
name	`string`	Defines the `alt` attribute for the flag image. Defaults to an empty string `""`, making the flag invisible to screen readers when no accessible name is needed.
role	`React.HTMLAttributes<HTMLImageElement>["role"]`	ARIA role for the flag image. The `name` prop should be used instead as it provides better screen reader support.

Automatic Accessibility Features

The component automatically applies the name prop value as the alt attribute on the flag image.
When name is empty (default), the flag is treated as decorative and is not announced by screen readers.
Focus management is not applicable as the component is not interactive.

Best Practices

Use the name prop to provide an accessible name when the flag conveys important information.
Leave name empty when the flag is purely decorative or when country information is provided by adjacent text.
Avoid providing a name value that duplicates text content placed immediately next to the flag, as this creates redundant announcements for screen reader users.
Prefer using the name prop over the role prop for better cross-platform screen reader support.
When displaying multiple flags in a list or grid, ensure each flag has a meaningful and unique accessible name when necessary.
Always localize country names in the name prop to match the user’s language preferences for proper screen reader pronunciation and comprehension.

The CountryFlag component is not interactive and does not receive keyboard focus. No keyboard navigation is applicable.

Examples

Note: Country names in examples are shown in English for demonstration purposes. In production, always use localized country names appropriate for your user’s language.

Flag with accessible name

<CountryFlag code="cz" name="Czech Republic" />

Screen reader announces: “Czech Republic, image”

Decorative flag next to text label

<Stack direction="row" spacing="100" align="center">
  <CountryFlag code="cz" />
  <Text>Czech Republic</Text>
</Stack>

Screen reader announces: “Czech Republic” (only the text is announced)

Flag in a list context

<Stack direction="column">
  <CountryFlag code="us" name="United States" />
  <CountryFlag code="ca" name="Canada" />
  <CountryFlag code="mx" name="Mexico" />
</Stack>

Screen reader announces: “United States, image”, “Canada, image”, “Mexico, image”

Flag without accessible name (decorative)

<CountryFlag code="gb" />

Screen reader announces: (nothing - flag is treated as decorative)

CountryFlag