flag-icons

flag-icons is a static asset library that ships an SVG for every country and territory flag, in both 4x3 rectangular and 1x1 square aspect ratios, along with a compiled CSS (and SASS source) that turns each flag into a single background-image class. Instead of hand-sourcing individual flag SVGs and wiring up backgrounds yourself, you install the package and add two class names to an empty span to render a flag inline with text or as a standalone icon.

The project distributes through both npm and Composer from the same source tree, so it serves JavaScript and PHP projects alike, and the compiled CSS is also available via jsDelivr for drop-in CDN usage with no build step at all. A SASS entry point exposes configuration variables so consumers can restrict the build to only the countries they need, keeping bundle size proportional to actual usage rather than shipping all 271 flags by default.

What You Get

• 271 country/territory flags, each shipped as both a 4x3 rectangular SVG and a 1x1 square SVG variant
• Pre-compiled flag-icons.css and minified flag-icons.min.css ready to drop in via <link>, npm import, or the jsDelivr CDN
• A SASS entry point (sass/flag-icons.scss) with configurable variables to build a CSS file containing only the countries you actually use
• Simple two-class markup (fi + fi-xx country code) that works on any empty element, with a fis modifier for square flags
• Parallel Composer package (lipis/flag-icons) and a Maven publish path, so the same asset set reaches PHP and JVM ecosystems too

Common Use Cases

• Rendering a country flag next to a phone-number country-code selector or address form
• Building a language/locale switcher where each option is paired with its national flag
• Showing per-region availability or pricing in an admin dashboard or marketing page
• Adding flags to a leaderboard, sports-scores widget, or nationality field in a user profile

Under The Hood

Architecture There’s no runtime code to execute — the project is a static data-to-CSS pipeline. Flag pixel data lives as SVGs under flags/4x3 and flags/1x1 (one pair per country/territory), country.json holds the canonical list of country codes and names, and sass/_flag-icons-list.scss iterates that list through a flag-icon($country) mixin defined in _flag-icons-base.scss to emit one .fi-xx background-image rule per flag. The compiled output (css/flag-icons.css and its minified twin) is checked into the repo alongside the SASS source, so consumers can use either the source SASS or the pre-built CSS without running a build themselves. Changing the core class contract (fi/fib/fis) or the SVG path convention would break every consuming site’s flag rendering, but there’s no service, database, or dependency-injection layer to reason about beyond this static generation step.

Tech Stack Build tooling is Sass 1.89.2 (SCSS compiled to CSS), SVGO 3.3.3 for SVG optimization via svgo.config.js, Prettier 3.6.2 for formatting, and http-server 14.1.1 for local preview at yarn start. Two small standalone Python scripts (flags.py, flag-ids.py) regenerate the country/flag ID lists outside the JS toolchain. The same asset tree is republished under three ecosystems from one source: npm (flag-icons), Composer (lipis/flag-icons), and Maven via maven.sh, plus a GitHub Pages demo site built from the checked-in index.html.

Code Quality There is no unit-test suite in the conventional sense — the test script only runs prettier --list-different to check formatting. Correctness is instead enforced structurally: a GitHub Actions workflow runs flags.py on every pull request, which cross-checks every SVG filename against country.json and fails the build if a flag file and a country entry are ever out of sync. A second workflow enforces the Prettier format check, and a third automates npm publishing on GitHub release. There are no type annotations or linters beyond Prettier, which fits the project’s scope as a data/asset package rather than an application.

What Makes It Unique The library’s main technical choice is distributing the exact same optimized SVG/CSS asset set across three package ecosystems (npm, Composer, Maven) from a single source of truth, rather than maintaining separate ports per language community. Its SASS configuration variables ($flag-icons-included-countries, custom $flag-icons-path) let consumers compile a CSS subset containing only the flags they use, which is a more deliberate size/usage tradeoff than most icon-font or sprite-sheet flag libraries offer. Beyond that, the approach — SVG assets plus generated background-image CSS classes — is a standard, well-understood pattern rather than a novel technical contribution.