@boxicons/js

JavaScript library for Boxicons with full tree-shaking support. Inspired by Lucide.

Installation

npm install @boxicons/js
# or
yarn add @boxicons/js
# or
pnpm add @boxicons/js

Usage

With ESModules (Recommended)

To reduce bundle size, @boxicons/js is built to be fully tree-shakable. The getIcons function will search for HTMLElements with the attribute data-bx and replace them with the SVG from the given icon name.

<!-- Your HTML file -->
<i data-bx="menu"></i>
<i data-bx="arrow-right"></i>
<i data-bx="globe"></i>

import { getIcons, Menu, ArrowRight, Globe } from '@boxicons/js';

// Recommended way, to include only the icons you need.
getIcons({
  icons: {
    Menu,
    ArrowRight,
    Globe
  }
});

With unpkg (CDN)

<!DOCTYPE html>
<body>
  <i data-bx="menu" class="my-class"></i>
  <i data-bx="home"></i>
  <i data-bx="alarm"></i>

  <script src="https://unpkg.com/@boxicons/js@latest"></script>
  <script>
    // When using CDN, all icons are available
    boxicons.getIcons({ icons: boxicons.icons });
  </script>
</body>

Custom Element Binding

import { createElement, Menu } from '@boxicons/js';

const menuIcon = createElement(Menu); // Returns HTMLElement (svg)

// Append HTMLElement in the DOM
const myApp = document.getElementById('app');
myApp.appendChild(menuIcon);

Custom Element Binding with Custom Attributes

import { createElement, Menu } from '@boxicons/js';

const menuIcon = createElement(Menu, {
  className: 'my-custom-class icon',
  fill: '#333',
  size: 'lg'
}); // Returns HTMLElement (svg)

// Append HTMLElement in the DOM
const myApp = document.getElementById('app');
myApp.appendChild(menuIcon);

Advanced Usage

Additional Options

In the getIcons function you can pass some extra parameters:

nameAttr - adjust the attribute name to look for (default: data-bx)
attrs - pass additional custom attributes to all icons
root - provide a custom DOM element or shadow root to search within
inTemplates - also replace icons inside <template> tags

import { getIcons, Menu, Home } from '@boxicons/js';

getIcons({
  icons: { Menu, Home },
  attrs: {
    className: 'my-custom-class icon',
    fill: '#333'
  },
  nameAttr: 'data-bx',
  root: document.getElementById('app'),
  inTemplates: true
});

Shadow DOM Support

You can use icons inside Shadow DOM by passing the shadow root as the root option:

import { getIcons, Menu, Home } from '@boxicons/js';

// Create a custom element with shadow DOM
class MyComponent extends HTMLElement {
  constructor() {
    super();
    const shadow = this.attachShadow({ mode: 'open' });
    shadow.innerHTML = `
      <i data-bx="menu"></i>
      <i data-bx="home"></i>
    `;
    
    // Replace icons inside the shadow root
    getIcons({
      icons: { Menu, Home },
      root: shadow
    });
  }
}

customElements.define('my-component', MyComponent);

Template Tags Support

To replace icons inside <template> tags, set inTemplates: true:

import { getIcons, Menu, Home } from '@boxicons/js';

getIcons({
  icons: { Menu, Home },
  inTemplates: true
});

<template id="my-template">
  <i data-bx="menu"></i>
  <i data-bx="home"></i>
</template>

Icon Packs

Each icon can have multiple variants:

basic - Outline/regular style icons (default for most icons)
filled - Solid/filled style icons
brands - Brand/logo icons (default for brand icons)

<i data-bx="alarm"></i>
<i data-bx="alarm" data-bx-pack="filled"></i>

Sizing

Size Presets

<i data-bx="alarm" data-bx-size="xs"></i>   <!-- 16px -->
<i data-bx="alarm" data-bx-size="sm"></i>   <!-- 20px -->
<i data-bx="alarm" data-bx-size="base"></i> <!-- 24px (default) -->
<i data-bx="alarm" data-bx-size="md"></i>   <!-- 36px -->
<i data-bx="alarm" data-bx-size="lg"></i>   <!-- 48px -->
<i data-bx="alarm" data-bx-size="xl"></i>   <!-- 64px -->
<i data-bx="alarm" data-bx-size="2xl"></i>  <!-- 96px -->
<i data-bx="alarm" data-bx-size="3xl"></i>  <!-- 128px -->
<i data-bx="alarm" data-bx-size="4xl"></i>  <!-- 256px -->
<i data-bx="alarm" data-bx-size="5xl"></i>  <!-- 512px -->

Custom Sizing

<i data-bx="alarm" data-bx-width="32" data-bx-height="32"></i>

Transformations

<!-- Flip -->
<i data-bx="alarm" data-bx-flip="horizontal"></i>
<i data-bx="alarm" data-bx-flip="vertical"></i>

<!-- Rotate -->
<i data-bx="alarm" data-bx-rotate="45"></i>
<i data-bx="alarm" data-bx-rotate="90"></i>

Styling

<!-- Custom fill color -->
<i data-bx="alarm" data-bx-fill="#ff0000"></i>

<!-- Opacity -->
<i data-bx="alarm" data-bx-opacity="0.5"></i>

<!-- Remove padding -->
<i data-bx="alarm" data-bx-remove-padding></i>

Programmatic Usage

import { createElement, createSvgString, Menu } from '@boxicons/js';

// Get SVG as a string
const svgString = createSvgString(Menu, { size: 'lg', fill: '#ff0000' });

// Get SVG as an element
const svgElement = createElement(Menu, { size: 'lg', fill: '#ff0000' });
document.body.appendChild(svgElement);

Accessibility

By default, icons are hidden from screen readers using aria-hidden="true".

You can add accessibility attributes using aria-labels:

<i data-bx="home" aria-label="Home icon"></i>

API Reference

Core Functions

Function	Description
`getIcons(options)`	Scan DOM for `data-bx` elements and replace with SVGs
`createElement(icon, options)`	Create an SVG DOM element from an icon
`createSvgString(icon, options)`	Create an SVG string from an icon

GetIconsOptions

Option	Type	Default	Description
`icons`	`IconsRecord`	required	Object containing icons to use
`nameAttr`	`string`	`'data-bx'`	Attribute name to look for
`attrs`	`IconOptions`	`{}`	Default attributes for all icons
`root`	`Element \| Document \| ShadowRoot`	`document`	Root element to search within (supports Shadow DOM)
`inTemplates`	`boolean`	`false`	Also replace icons inside `<template>` tags

Data Attributes

Attribute	Description
`data-bx`	Icon name (required)
`data-bx-pack`	Icon pack: 'basic', 'filled', 'brands'
`data-bx-size`	Size preset: 'xs', 'sm', 'base', 'md', 'lg', 'xl', '2xl', '3xl', '4xl', '5xl'
`data-bx-width`	Custom width
`data-bx-height`	Custom height
`data-bx-fill`	Fill color
`data-bx-opacity`	Opacity (0-1)
`data-bx-flip`	Flip direction: 'horizontal', 'vertical'
`data-bx-rotate`	Rotation in degrees
`data-bx-remove-padding`	Remove icon padding (presence = true)

TypeScript

Full TypeScript support with exported types:

import type { 
  IconDefinition, 
  IconOptions, 
  IconPack, 
  IconSize, 
  FlipDirection,
  GetIconsOptions,
  IconsRecord
} from '@boxicons/js';

Tree Shaking

This library is fully tree-shakeable. Only the icons you import will be included in your final bundle:

// ✅ Only Menu and Home are bundled
import { getIcons, Menu, Home } from '@boxicons/js';

getIcons({ icons: { Menu, Home } });

// ❌ This bundles ALL icons - avoid in production
import { getIcons, icons } from '@boxicons/js';
getIcons({ icons });

License

MIT

box-icons/boxicons