@odx/flag-icons NPM

@odx/flag-icons

A lightweight library for displaying flag icons as custom elements. This package provides flexible imports, allowing you to include only what you need to optimize your project.

Installation (npm)

Install the library via npm:

npm i @odx/flag-icons

Usage

The library provides a custom custom element <odx-flag-icon> to display flag icons. You can choose between different sets (1x1 or 4x3) or import individual flags to reduce your bundle size.

We rely on the esm module behavior in order to keep a global state. If you load an asset from a CDN ensure that the same module of @odx/assets-utils is used throughout your application. One common technique is the usage of an import map (<script type="importmap">).

Import custom element:

import '@odx/flag-icons';

Import specific flag icon sets

To optimize your bundle, you can import only the specific flag icon set you need:

// All flag icon sets
import '@odx/flag-icons/all';

// Square flag icons (1x1 aspect ratio)
import '@odx/flag-icons/1x1';

// Rectangular flag icons (4x3 aspect ratio) (default set)
import '@odx/flag-icons/4x3';

Import individual icons

To optimize your bundle, you can import only the specific flag icons you need:

import '@odx/flag-icons/4x3/de';

Example Usage

Element API

name: string - <set-name>::<name> or <name> with default set (4x3)
set: string - <set-name>
size: string - one of xs | sm | md | lg

Size Attribute

The size attribute provides predefined size options for the flag icon. These options correspond to CSS variables that can be customized globally in your project. The available values are:

xs: --odx-size-100 - fallback: 16px
sm: --odx-size-125 - fallback: 20px
md: --odx-size-150 - fallback: 24px
lg: --odx-size-200 - fallback: 32px
xl: --odx-size-225 - fallback: 36px

The size tokens (--odx-size-*) are provided by the @odx/design-tokens package.

CSS Custom Properties

--size: string - Defines the size of the flag icon. The default value is 1em, which matches the current font size. This can be overridden using the size attribute or custom CSS

HTML Example

<script type="module">
  import '@odx/flag-icons/4x3';
</script>

<odx-flag-icon name="de" set="4x3"></odx-flag-icon>

CDN

<script src="https://esm.sh/@odx/flag-icons" type="module"></script>
<script src="https://esm.sh/@odx/flag-icons/<set-name>" type="module"></script>

JavaScript Example

// Import the 1x1 icon set
import '@odx/flag-icons/1x1';

// Create a flag dynamically
const flagIcon = document.createElement('odx-flag-icon');
flagIcon.name='1x1::de'

document.body.appendChild(flagIcon);

CDN

import loadFlagIcons from '@odx/flag-icons/loader';

/*
interface AssetLoaderOptions {
  cdn?: string; // default: 'https://esm.sh'
  loadCustomElement?: boolean; // default: false
  loadMetadata?: boolean; // default: false
}
*/
loadFlagIcons('<set-name>', options);

SCSS Example

@use "@odx/flag-icons/main" as odxFlagIcons;

.flag-de-1x1 {
  @include odxFlagIcons.flag-icon("1x1::de");
}

.flag-de-4x3 {
  @include odxFlagIcons.flag-icon("4x3::de");
}

Browser Support

This library leverages modern web technologies such as Shadow DOM for encapsulation and CSSStyleSheet.replaceSync() for efficient stylesheet updates. It targets the ES2022 specification, taking advantage of the latest JavaScript features. These technologies are widely supported in most modern browsers.