flag-icon | Vaadin

Polymer Web Component for SVG icons of country, state, province and other flags.

[ This description is mirrored from README.md at github.com/Protoss78/flag-icon on 2019-05-22 ]


A collection of SVG flags, conveniently usable as a Polymer Web Component.

If you don't care about extra features, a simple CSS implementation of country flags can be found at https://github.com/lipis/flag-icon-css

Typical file sizes:

SVG files: 2kb to 75kb

Component Page

API Documentation and Demo


  1. Add the library using the Javascript package manager Bower:

    bower install --save flag-icon

  2. Import Web Components' polyfill:

    <script src="bower_components/webcomponentsjs/webcomponents.min.js"></script>
  3. Import Custom Element:

    <link rel="import" href="bower_components/flag-icon/flag-icon.html">
  4. Start using it!

    <flag-icon key="ca"></flag-icon>
    <flag-icon key="canada"></flag-icon>
    <flag-icon key="124"></flag-icon>
    <!-- specify to use PNGs -->
    <flag-icon key="ca" img></flag-icon>
    <!-- specify a specific size -->
    <flag-icon key="ca" width="100"></flag-icon>
    <!-- Specify alt & title text,
         otherwise it defaults to the official country name -->
    <flag-icon key="can">Flag of Canada</flag-icon>
  5. Or use it unrendered in scripts:

    var f = new FlagIcon();
    //get country info
    //> { name: 'Canada', alpha2: 'CA', alpha3: 'CAN', numeric: 124 }
    //convert between 2 -> 3 letter character codes
    //> 'CAN'
    //get full names of states or provinces
    //> { name: 'California', iso: 'US-CA', alpha2: 'CA', numeric: 6, gpo: 'Calif.' }
    //> { name: 'Ontario', alpha2: 'ON' }


Attribute Type Default Description
key string null Proper, common, ISO 3166-1 alpha-2, alpha-3, or country code
au boolean false Australia Australian State flags
br boolean false Brazil Brazilian State flags
ca boolean false Canada Canadian Province and Territory flags
de boolean false Germany German State flags
es boolean false Spain Spain Autonomous Community flags
ru boolean false Russia Russian Republics, Krais, and Oblast flags
us boolean false United States US State flags
maritime boolean false Maritime and ICS flags
racing boolean false NASCAR and IndyCar racing flags
square boolean false Use square version instead of 4:3 aspect (only valid for country flags)
aspect float Override aspect ratio used to render the flag

Aspect Ratios for Flags

Flags come in all different shapes and sizes, attempts were made to standardize to the following aspect ratios (width:height)

Attribute Aspect
Country 4:3
Austrialia 2:1
Brazil 3:2
Canada 2:1
Germany 5:3
Spain 3:2
US 3:2
Russia 3:2
NASCAR, IndyCar 4:3
Maritime 1:1


  • Loading notification, or default image.
  • Compact/minify SVG files


For detailed changelog, check Releases.


MIT License © Steven Skelton


Link to this version
ImportedReleased 18 July 2017MIT License
Framework Support
Polymer 2.0+
Also supported:
Polymer 1 (0.12.0)
Browser Compatibility
Install with
bower install --save Protoss78/flag-icon"#1.0.1"
Run the above Bower command in your project folder. If you have any issues installing, please contact the author.
Release notes - Version 1.0.1


  • polymer#Polymer/polymer#1.9 - 2
  • iron-image#PolymerElements/iron-image#1 - 2
  • iron-flex-layout#PolymerElements/iron-flex-layout#1 - 2