FlagKit: PNG and SVG flag icons for iOS, macOS and tvOS

What FlagKit is for, and who should reach for it

FlagKit solves one narrow problem: getting a correct-looking national flag into an interface without commissioning artwork or curating a folder of mismatched images. The repository describes the flags as "Beautiful flag icons for usage in apps and on the web", and it distributes them in two forms. Every flag exists as a standalone PNG and as a standalone SVG. On top of those files, the project adds an Asset Catalog and a Swift framework so Apple-platform code can ask for a flag by country code instead of by filename.

The audience is therefore an Apple developer. The topics list confirms the target: flag-icons, flags, icons, ios, macos, tvos. If you are writing a settings screen that shows the user's region, a country picker, a currency or locale selector, or a list of supported shipping destinations, FlagKit is the kind of dependency you add once and stop thinking about. It is not a mapping library, not a geolocation service, and not a data source for country metadata. It supplies images and the plumbing to load them.

That narrowness is the point. A project that only draws flags can be small, and FlagKit is small: a Package.swift, an Assets directory, a Sources directory, a licence and a README.

How the framework turns a country code into an image

The mechanism is deliberately thin. The Asset Catalog stores each flag under its country code as the asset name, and the framework wraps access to that catalog. The README's example takes Locale.current.regionCode, constructs a Flag from it, and then asks for either the unstyled original or a styled variant. The styled variant takes a style argument, and the README names three shapes the sample project demonstrates: rounded corners, square and circle.

There are two access paths, and the difference matters when you are debugging. The typed path goes through the Flag type and returns nil for an unknown code, which is why the README's example force-unwraps after reading the current locale. The untyped path goes straight to the bundle: you fetch FlagKit.assetBundle and call UIImage(named:in:compatibleWith:) with the country code as the asset name. That second path is useful when you want to bypass the wrapper, but it also means you lose whatever validation the typed path performs. If an image fails to appear, check the country code string against Assets/Flags.md before you suspect the framework.

Styling is where the platform split appears. The README carries an explicit note that styling is currently not supported by FlagKit on macOS. On iOS and tvOS you can ask for a circle; on macOS you get the unstyled asset. That is a real architectural boundary, not a documentation gap, and it should shape which platforms you target with styled UI.

Installing FlagKit with SwiftPM, Carthage or a manual copy

The README gives three installation routes for iOS, macOS and tvOS. SwiftPM is the first. Add the repository URL as a package dependency; the README lists the URL as https://github.com/madebybowtie/FlagKit.git. The repository also has a Package.swift at its top level, which is what makes that route work.

https://github.com/madebybowtie/FlagKit.git

That line is the repository URL the README tells you to enter as the package dependency, not a shell command. In Xcode you add it through the package dependency dialog; in a Package.swift manifest you reference it as a package dependency and then list FlagKit as a target dependency.

The second route is Carthage. Add one line to your Cartfile, and the README gives the exact form.

github "madebybowtie/FlagKit"

After that, run your usual Carthage update and link the built framework. The third route skips dependency managers entirely: copy Assets/FlagKit.xcassets into your target. That is the option to consider if you want the images without the framework, or if you are vendoring assets into a project that cannot take external dependencies.

Once installed, the first real use is the snippet from the README. It resolves the current region, builds a Flag, and produces both an unstyled and a styled image.

let countryCode = Locale.current.regionCode!
let flag = Flag(countryCode: countryCode)!

// Retrieve the unstyled image for customized use
let originalImage = flag.originalImage

// Or retrieve a styled flag
let styledImage = flag.image(style: .circle)

What you should see is an image for the device's current region. If regionCode is nil, the force-unwrap traps, so production code should handle that case rather than copying the example literally. The README also shows the direct catalog access path, which is the fallback when you want the raw asset.

let countryCode = Locale.current.regionCode!
let bundle = FlagKit.assetBundle
let originalImage = UIImage(named: countryCode, in: bundle, compatibleWith: nil)

Here the country code doubles as the asset name inside the bundled catalog. The README links a full list of flags at Assets/Flags.md, which is the file to consult when you need to confirm that a particular code is covered.

The platform boundary: no Android, no React Native, no web package

The most consequential limitation is what the repository does not contain. The topics and the installation section cover iOS, macOS and tvOS. There is no Android artifact, no React Native module, no JavaScript or npm package, and no web component in the top-level entries. The README says the flags are for "usage in apps and on the web", but that phrase describes the file formats, not a distribution channel: PNG and SVG files can be dropped into a web project, yet nothing in this repository automates that.

So if your product is an Android app, a React Native app or a browser front end, FlagKit is the wrong dependency. You can still use the artwork, because the PNG and SVG files are standalone, but you would be copying files and managing updates yourself. That is a meaningful maintenance difference from the Apple path, where SwiftPM or Carthage handles versioning.

The second limitation is the macOS styling gap already noted. A cross-platform Apple codebase that renders circular flags on iOS will need a different treatment on macOS, or it will render unstyled art there. The README states this plainly rather than hiding it, which is the right call, but it does mean the framework's API surface is not uniform across the platforms it claims to support.

A third constraint is scope. FlagKit provides over 250 flags according to the README. It is a static set. If your application needs flags that are not in that set, or needs to update flags independently of a framework release, the bundled catalog model works against you. The standalone SVG and PNG files are the escape hatch, and for a handful of exceptions that is fine; for a large or frequently changing set it is not.

FlagKit compared with a generic icon set

The realistic alternative is not another flag library; it is a general-purpose icon package that happens to include flags. Font Awesome and similar icon fonts and SVG sets ship flag glyphs alongside thousands of unrelated icons. The difference in approach is structural. A general icon set gives you a font or a sprite and expects you to render a glyph by name, which means flag appearance depends on the set's design choices and on your text rendering pipeline. FlagKit instead ships each flag as a discrete image asset and, on Apple platforms, exposes it through a typed API keyed by country code.

That matters for two reasons. First, correctness of the country code becomes a compile-time-adjacent concern: you pass a code, not a glyph name, and the README's list at Assets/Flags.md is the reference. Second, styling is handled by the library rather than by CSS or font tricks, which is why the circle, square and rounded-corner shapes exist as an argument to image(style:). With an icon font you would typically mask or clip the glyph yourself.

The trade-off runs the other way too. A general icon set covers far more than flags, so if you already depend on one, adding FlagKit means a second dependency and a second visual language. Flag artwork from two sources will not match, and mismatched flag styles in one interface look like a bug. Pick one source for flags and use it everywhere.

Maintenance, upgrading and the MIT licence

The repository is not archived, and the last push was on 2026-09-25, with release v2.5.0 tagged the same day. Before that, the release history shows a long gap: 2.4.0 arrived on 2021-05-04 with the note "Support for arm64 Macs", and v2.3.0 on 2021-03-13 with the note "SwiftPM". So the pattern is long quiet periods punctuated by maintenance releases. Plan for that cadence rather than assuming a steady stream of updates.

Upgrade cost is low on the SwiftPM and Carthage paths. The public surface shown in the README is a Flag type, an originalImage property, an image(style:) method, and the assetBundle accessor. A dependency with that little API is unlikely to break your build often. The manual route is different: if you copied Assets/FlagKit.xcassets into your target, upgrading means copying the catalog again by hand, and any local edits you made to those assets will need to be reapplied. That is the hidden cost of avoiding a dependency manager.

FlagKit is released under the MIT licence, and the repository carries a LICENSE file at its top level. MIT is permissive, which generally means you can use the assets and framework in commercial and closed-source products provided the licence terms are honoured. This is not legal advice; read the LICENSE file and your own organisation's policy before shipping, particularly if you are redistributing the flag artwork itself rather than only linking the framework.

Editorial conclusion

Adopt FlagKit if you are building an Apple-platform app that needs country flags and you want them as an Asset Catalog or SwiftPM dependency rather than hand-managed image files. Do not adopt it for Android, React Native, web-only or server-rendered targets: the repository has no Android, React Native or JavaScript package, and the README points those users at the standalone PNG and SVG files in Assets/. Before you commit, verify that the country codes you need are present in Assets/Flags.md, and check on macOS whether you need styled output, because the README states styling is not supported there.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. madebybowtie/FlagKit on GitHub
4. README
5. Releases