---
title: Flag
description: A country or region flag in its drawn 4:3 or 1:1 artwork, served from a cached route or your own web server.
visibility: guest
draft: false
---

# Flag

The `<x-wirekit::flag>` component shows the flag of a country or region. The artwork ships with WireKit and is served from a route with a one-year cache, so nothing needs installing.

## Serving the Files Yourself

Nothing is required. A flag reaches the page through a WireKit route, cached for a year, and a page that shows no flag loads none of it.

To let your web server deliver the files instead — one fewer PHP request per flag on a page that shows many:

```bash
php artisan vendor:publish --tag=wirekit-flags
```

After a WireKit update, publish again with `--force`. Until then WireKit keeps using its route, because it links a published copy only while that copy's manifest matches the one it ships with.

## Basic Usage

`country` takes an ISO 3166-1 alpha-2 code, in any case. A flag is decorative by default, which suits the usual place for one, next to the country's name:

:::preview{title="Flag beside a country name"}
<x-wirekit::row gap="sm">
    <x-wirekit::flag country="de" />
    <x-wirekit::text>Germany</x-wirekit::text>
</x-wirekit::row>
:::

## Shapes

`shape` chooses the artwork. `rect` shows the 4:3 artwork and is the default, `square` shows the 1:1 artwork, and `circle` crops the 1:1 artwork round. No artwork is stretched to a ratio it was not drawn for.

:::preview{title="Rect, square and circle"}
<x-wirekit::row gap="md">
    <x-wirekit::flag country="jp" shape="rect" />
    <x-wirekit::flag country="jp" shape="square" />
    <x-wirekit::flag country="jp" shape="circle" />
</x-wirekit::row>
:::

## Sizes

`size` sets the height on the same steps as the icon component, so a flag lines up with an icon of the same size: `xs` is 12px, `sm` 16px, `md` 20px, `lg` 24px and `xl` 32px. The default is `md`, and the width follows from the shape.

:::preview{title="Every size"}
<x-wirekit::row gap="md">
    <x-wirekit::flag country="br" size="xs" />
    <x-wirekit::flag country="br" size="sm" />
    <x-wirekit::flag country="br" size="md" />
    <x-wirekit::flag country="br" size="lg" />
    <x-wirekit::flag country="br" size="xl" />
</x-wirekit::row>
:::

## A Flag That Stands Alone

Without a name beside it, a flag carries the information itself, so give it one with `alt`:

:::preview{title="Informative flag"}
<x-wirekit::flag country="fr" size="lg" alt="France" />
:::

## Regions, Organizations and Your Own Flags

Besides every ISO 3166-1 country, WireKit carries flags for some regions and organizations, such as `eu`, `un`, `gb-sct` and `es-ct`. `resources/flags/flags.json` lists every code there is artwork for.

For a flag it does not carry, pass your own image with `src`. It gets the same size, shape and outline:

```blade
<x-wirekit::flag src="/images/flags/bavaria.svg" alt="Bavaria" />
```

## When a Flag Is Missing

| Situation | What renders | What you are told |
| --- | --- | --- |
| a code the artwork carries | the flag | nothing |
| a code it does not carry | a placeholder of the same size | one warning per code in the log, in debug mode only |
| `flags.path` points somewhere with no `flags.json` | a placeholder of the same size | one warning in the log naming that setting — one, not one per flag |

A placeholder takes the flag's box, so a list of countries keeps its alignment when one flag is missing. It is decorative unless the flag was given an `alt`.

The third row is the only way to reach a page of placeholders, and it takes a deliberate setting to get there: the artwork ships with WireKit, so leaving `flags.path` unset is what you want unless you keep the files somewhere else.

## Configuration

```php
// config/wirekit.php
'components' => [
    'flag' => ['size' => 'md', 'shape' => 'rect'],
],

// Only for artwork kept somewhere other than the package's own resources/flags.
'flags' => [
    'path' => env('WIREKIT_FLAGS_PATH'),
],
```

## How Flags Are Served

Each flag is an `<img>` with `loading="lazy"`, not inline SVG, so a list of every country costs one small cached request per flag instead of megabytes of HTML. The URL carries the checksum of the file itself, which lets the response be cached for a year and still change on the day the file does.

The route serves only the flags the package's manifest lists. Its responses carry `X-Content-Type-Options: nosniff` and a Content Security Policy that allows no script, request or plugin, because a browser that opens an SVG directly treats it as a document.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `country` | `string` | `null` | A code the shipped artwork carries, such as `de` or `gb-sct`. Case does not matter. |
| `src` | `string` | `null` | A URL to a flag of your own. Wins over `country`. |
| `shape` | `string` | `rect` | `rect` (4:3), `square` or `circle` (both 1:1). |
| `size` | `string` | `md` | `xs`, `sm`, `md`, `lg` or `xl`. |
| `alt` | `string` | `''` | The flag's name. Leaving it empty makes the flag decorative. |
| `scope` | `string` | `null` | A class-override scope, as on every component. |

## Accessibility

- A flag is decorative by default (`alt=""`). Next to the country's name, announcing the name twice is noise.
- Give a flag that stands alone an `alt`. A placeholder then takes that name too, as `role="img"`.
- A hairline outline keeps a white flag's edge visible in light and dark themes. Under forced colors it uses the system's gray.

## Keyboard Interaction

This component is purely presentational and does not respond to keyboard input.