Juni 2018Okt. 2019Feb. 2021Juni 2022Nov. 2023März 2025Juli 2026
Artefaktenpmnpm install boxicons
README
@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
});
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)
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 });