# Country Flag Emoji — card for AI agents

JavaScript library listing country codes with their flag emojis, Unicode sequences and country names.

Category: Emoji · maker Risan Bagja Pradana · checked 2026-11-11

## Price
- Price: Free
- Free tier: Free and open source under the MIT license

## License
MIT License — https://github.com/risan/country-flag-emoji/blob/HEAD/LICENSE

- commercial: **yes** (Commercial use OK)
  > to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software
  (https://github.com/risan/country-flag-emoji/blob/HEAD/LICENSE)
- attribution: **no** (No credit needed)
  > The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
  (https://github.com/risan/country-flag-emoji/blob/HEAD/LICENSE)
- in app: **yes** (Can ship inside your app)
  > Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files
  (https://github.com/risan/country-flag-emoji/blob/HEAD/LICENSE)

## Rules to follow
- Keep the MIT license and copyright notice with any copies or substantial portions you distribute.
- Install via npm (country-flag-emoji) or the unpkg CDN rather than copying data by hand.
- Look up flags by ISO 3166-1 alpha-2 country code with get().

## Can an AI agent use it by itself?
**Yes** · package: Agent installs a package or loads it from a CDN

## How to connect
- Package (npm/PyPI)
- npm: `npm install country-flag-emoji`
- Repository: https://github.com/risan/country-flag-emoji
- Website: https://github.com/risan/country-flag-emoji

## Notes
Added automatically; license read from the official pages.

## Numbers (AgentGid data)
- Gid Score: 20
- GitHub stars: 40
- Downloads last week: 11,304

## Lines to paste into your prompt or AGENTS.md

```
- Country Flag Emoji (Emoji). JavaScript library listing country codes with their flag emojis, Unicode sequences and country names. Price: free; commercial use OK; no credit needed.
  Connect: npm country-flag-emoji.
  Rule: Keep the MIT license and copyright notice with any copies or substantial portions you distribute.
  Rule: Install via npm (country-flag-emoji) or the unpkg CDN rather than copying data by hand.
  Rule: Look up flags by ISO 3166-1 alpha-2 country code with get().
  License: https://github.com/risan/country-flag-emoji/blob/HEAD/LICENSE (checked 2026-11-11; details: https://agentgid.com/assets/country-flag-emoji/)
```

## Links
- AgentGid page: https://agentgid.com/assets/country-flag-emoji/
- Is it free for commercial use? https://agentgid.com/assets/country-flag-emoji/commercial-use/
- Source: https://github.com/risan/country-flag-emoji/blob/HEAD/LICENSE
- Source: https://github.com/risan/country-flag-emoji


## Country Flag Emoji: flags and names for every country code

Country Flag Emoji is a small free code library with a list of countries and regions. For each two-letter code like DE or JP it gives the name and the flag emoji. The flags are text characters, so the visitor's own emoji font draws them.

### Where to use it
- Flag next to a country code: Your database stores a two-letter code such as FR for each order or user. One call turns it into the country name and its flag for a table or a profile.
- Country list for a form: Fill the country menu of a sign-up, shipping or billing form with every name and flag from one list. Typing a few letters can narrow it down.
- Flags on a page without a build step: A plain HTML page, like a landing page or an old site, can load the library with one script tag and use the same list.
- Sales or visitors by country: Put a flag in front of each country in a small report, such as orders per country, so people find their row at a glance. (idea, not from the official pages)
- Region switcher in the header: Show the flag of the chosen country in a shop's region or currency menu, next to its name, not instead of it. (idea, not from the official pages)

### How to start
- Add the package to your project.

```
$ npm install country-flag-emoji
```

- Import it and look up a country by its two-letter code, or use the full list.

```
import countryFlagEmoji from "country-flag-emoji";

// Array of all country flag emojis
console.log(countryFlagEmoji.list);

// Get country flag emoji for the given country code
console.log(countryFlagEmoji.get("US"));
```


### License
Free for personal and paid products under the MIT License, with no visible credit needed. Keep the short copyright and permission notice with copies of the code.

### Good to know
- The last release, 1.0.3, came out in October 2019, so newer changes to country lists are not in it.
- It holds codes, names and emoji characters only, no flag pictures. How a flag looks depends on the emoji font of the visitor's device.
- Names are in English only, such as "United States"; there are no translated names.
- Looking up a code that is not in the list gives nothing back, so the page must handle a missing country.

Checked 2026-11-19 against: https://github.com/risan/country-flag-emoji, https://github.com/risan/country-flag-emoji/blob/HEAD/README.md, https://github.com/risan/country-flag-emoji/blob/HEAD/LICENSE, https://registry.npmjs.org/country-flag-emoji, https://registry.npmjs.org/country-flag-emoji/1.0.3

### Mistakes to avoid
- Don't: countryFlagEmoji.get(code).name with a code from user input → Do: const c = countryFlagEmoji.get(code); if (!c) show "Unknown country" (get() returns undefined for a code that is not in the list, so reading .name throws.)
- Don't: <script src="https://unpkg.com/country-flag-emoji@latest/dist/country-flag-emoji.umd.js"> → Do: Pin the version (country-flag-emoji@1.0.3) or install the package (The docs show @latest; a pinned version cannot change under your page.)
- Don't: Treat every entry of countryFlagEmoji.list as a country in a shipping form → Do: Filter the list against the countries you really ship to (In our demo the 258 entries include EU (European Union), UN (United Nations) and small territories such as AC and TA.)
- Don't: Use the flag emoji alone as the label of a menu item → Do: Show the country name next to the flag and keep the name as the accessible text (The flag is only an emoji character; its look depends on the device font and screen readers read it differently.)

### Questions
- Can I use it in a paid app? Yes. The MIT License allows use, copying and selling; keep the copyright and permission notice with copies of the code.
- Which codes does it use? Two-letter codes in the ISO 3166-1 alpha-2 format, such as US or ID.
- What does one entry contain? Four fields, code, unicode (the character sequence), name and emoji.
- Is it still updated? The newest version on the package registry is 1.0.3, published in October 2019.

---
AgentGid's catalog is curated: every entry was checked against the maker's official pages (registry, repository, license and pricing pages) on the date shown; a license value shows the quote it stands on wherever AgentGid has one. Usage numbers come from AgentGid's own scan of public repositories set up for AI coding agents. Claims by makers are reported, not tested by AgentGid.
