@boxicons/js

v1.0.1

Published

15 days ago

Vanilla JavaScript library for Boxicons with tree-shaking support

0High
0Medium
0Low

bxicons

boxicons icons javascript vanilla-js svg tree-shaking

@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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@boxicons/js

Installation

Usage

With ESModules (Recommended)

With unpkg (CDN)

Custom Element Binding

Custom Element Binding with Custom Attributes

Advanced Usage

Additional Options

Shadow DOM Support

Template Tags Support

Icon Packs

Sizing

Size Presets

Custom Sizing

Transformations

Styling

Programmatic Usage

Accessibility

API Reference

Core Functions

GetIconsOptions

Data Attributes

TypeScript

Tree Shaking

License