@boxicons/js Documentation

repository·main·Indexed 25 days ago

A lightweight, tree-shakable JavaScript library for using Boxicons in web projects. It allows developers to replace HTML elements with SVGs via data attributes or programmatic API calls. Key features include automatic DOM scanning with init(), manual replacement via getIcons(), and utilities for creating SVG strings or elements. Supports Shadow DOM, template tags, and Server-Side Rendering (SSR) compatibility.

Tokens: 4K
Snippets: 10
Records: 24
Agent score: 84%

What's inside @boxicons/js

Use @boxicons/js via CDN (unpkg)

main

You can use the library via unpkg. When using the CDN, all icons are available globally under the boxicons object.

<!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>

Support Shadow DOM and Templates

main

To use icons inside a Shadow DOM, pass the shadowRoot as the root option in getIcons. To replace icons inside <template> tags, set inTemplates: true.

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

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

Optimize Bundle Size with Tree Shaking

main

To keep your bundle small, import only the specific icons you need. Avoid importing the entire icons object from @boxicons/js in production.

// ✅ 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 });

Use @boxicons/js with ESModules (Recommended)
main
To ensure full tree-shaking support and minimize bundle size, import specific icons and use the getIcons function. The function scans the DOM for elements with the data-bx attribute and replaces them with the corresponding SVG.
```

<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
  }
});
```
https://github.com/box-icons/boxicons
Install @boxicons/js
main
Install the Boxicons JavaScript library using your preferred package manager.
```
npm install @boxicons/js
# or
yarn add @boxicons/js
# or
pnpm add @boxicons/js
```
https://github.com/box-icons/boxicons
Ensure Accessibility for Icons
main
By default, icons are hidden from screen readers using aria-hidden="true". To make them accessible, provide an aria-label.
```
<i data-bx="home" aria-label="Home icon"></i>
```
https://github.com/box-icons/boxicons

Create icons programmatically with createElement()

main

Use createElement to generate an SVG HTMLElement directly from an icon definition. You can pass an options object to customize the icon's appearance.

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

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

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

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

Create SVG strings with createSvgString()
main
Use createSvgString to generate the raw SVG string for an icon, which is useful for server-side rendering or manual string manipulation.
```
import { createSvgString, Menu } from '@boxicons/js';

// Get SVG as a string
const svgString = createSvgString(Menu, { size: 'lg', fill: '#ff0000' });
```
https://github.com/box-icons/boxicons

Configure icons via Data Attributes

main

You can customize icon appearance directly in HTML using data-bx attributes.

```html
<!-- Icon Pack -->
<i data-bx="alarm" data-bx-pack="filled"></i>

<!-- Sizing Presets -->
<i data-bx="alarm" data-bx-size="xs"></i>   <!-- 16px -->
<i data-bx="alarm" data-bx-size="base"></i> <!-- 24px (default) -->
<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 -->
<i data-bx="alarm" data-bx-flip="horizontal"></i>
<i data-bx="alarm" data-bx-rotate="45"></i>

<!-- Styling -->
<i data-bx="alarm" data-bx-fill="#ff0000"></i>
<i data-bx="alarm" data-bx-opacity="0.5"></i>
<i data-bx="alarm" data-bx-remove-padding></i>

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)

Configure getIcons() options

main

The getIcons function accepts an options object to control how the DOM is scanned and how icons are applied.

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

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

Core API functions for @boxicons/js
main
The @boxicons/js library provides several core functions to manage and render icons:
- getIcons: Retrieves icon data.
- createIcons: Automatically finds and replaces icon placeholders in the DOM with SVG icons.
- createElement: Creates a new icon element.
- createSvgString: Generates an SVG string for an icon.
- createSvgElement: Generates an SVG DOM element for an icon.
https://github.com/box-icons/boxicons/blob/main/src/index.ts
Configure icon replacement with CreateIconsOptions
main
When using the createIcons function, you can pass a CreateIconsOptions object to define how icons are searched for and replaced in the DOM.
Available Options:
- icons: A record of icons to use for replacement (IconsRecord).
- nameAttr: The attribute name to look for icon names. Defaults to 'data-bx'.
- attrs: Additional attributes to apply to all icons (uses IconOptions).
- root: Custom root element to search within (supports Element, Document, or ShadowRoot). Defaults to document.
- inTemplates: Whether to also replace icons inside <template> tags. Defaults to false.
https://github.com/box-icons/boxicons/blob/main/src/types.ts