@odx/pictograms NPM

@odx/pictograms

A lightweight library for displaying pictograms 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/pictograms

Usage

The library provides a custom custom element <odx-pictogram> to display pictograms. You can choose between different sets or import individual pictograms 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/pictograms';

Import specific pictogram sets

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

// All pictogram sets
import '@odx/pictograms/all';

// Default pictograms (default set)
import '@odx/pictograms/default';

Import individual pictograms

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

import '@odx/pictograms/default/user';

Example Usage

Element API

name: string - <set-name>::<name> or <name> with default set (core)
set: string - <set-name>

CSS Property API

--color: string - default: currentColor
--size: string - default: 1em

HTML Example

<script type="module">
  import '@odx/pictograms';
  import '@odx/pictograms/default';
</script>

<!-- default set: core -->
<odx-pictogram name="<name>"></odx-pictogram>
<odx-pictogram name="<set-name>::<name>"></odx-pictogram>
<odx-pictogram name="<set-name>::<name>"></odx-pictogram>

CDN

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

JavaScript Example

// Import the default pictogram set
import '@odx/pictograms/default';

// Create a pictogram dynamically
const pictogram = document.createElement('odx-pictogram');
pictogram.name = 'default::user';

document.body.appendChild(pictogram);

CDN

import loadPictograms from '@odx/pictograms/loader';

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

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.