### Install @boxicons/js
Source: https://github.com/box-icons/boxicons/blob/main/README.md
Install the library using npm, yarn, or pnpm.
```bash
npm install @boxicons/js
# or
yarn add @boxicons/js
# or
pnpm add @boxicons/js
```
--------------------------------
### Usage with unpkg CDN
Source: https://github.com/box-icons/boxicons/blob/main/README.md
Include the library via CDN and use the global `boxicons` object to get all available icons. This method makes all icons available.
```html
```
--------------------------------
### Tree Shaking with Boxicons JS
Source: https://github.com/box-icons/boxicons/blob/main/README.md
Demonstrates efficient bundling by importing only necessary icons. Avoid importing all icons to ensure a smaller production bundle.
```javascript
// ✅ 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 });
```
--------------------------------
### Auto-import Entry Point
Source: https://context7.com/box-icons/boxicons/llms.txt
Importing from `@boxicons/js/auto` automatically scans the document on `DOMContentLoaded` and sets up a `MutationObserver` for live updates. This is ideal for CDN or prototyping usage as it requires no manual calls.
```APIDOC
## Auto-import entry point — zero-config initialization
Importing from `@boxicons/js/auto` automatically scans the document on `DOMContentLoaded` and sets up a `MutationObserver` so newly added elements are processed without any manual call. All icons are included, so this entry point is not tree-shakable and is best suited for CDN/prototyping usage.
```html
```
```javascript
// ESM — automatic replacement + live observation of the DOM
import '@boxicons/js/auto';
// No further calls needed; icons already replaced and observer running.
// Access the MutationObserver instance to stop watching if needed
import { autoObserver } from '@boxicons/js/auto';
autoObserver?.disconnect();
```
```
--------------------------------
### Size Presets
Source: https://github.com/box-icons/boxicons/blob/main/README.md
Apply predefined size presets to icons using the `data-bx-size` attribute, ranging from 'xs' to '5xl'.
```html
```
--------------------------------
### Boxicons Auto-Import Initialization (CDN)
Source: https://context7.com/box-icons/boxicons/llms.txt
Include the `@boxicons/js/auto` script via CDN to automatically process icons on `DOMContentLoaded`. This is suitable for CDN or prototyping usage as it includes all icons and is not tree-shakable.
```html
```
--------------------------------
### Icon Packs
Source: https://github.com/box-icons/boxicons/blob/main/README.md
Use different icon packs like 'basic', 'filled', or 'brands' by specifying the `data-bx-pack` attribute on the icon element.
```html
```
--------------------------------
### Basic Usage with ESModules
Source: https://github.com/box-icons/boxicons/blob/main/README.md
Use the `getIcons` function to replace HTMLElements with the `data-bx` attribute with SVG icons. Ensure you import only the icons you need for tree-shaking.
```html
```
```javascript
import { getIcons, Menu, ArrowRight, Globe } from '@boxicons/js';
// Recommended way, to include only the icons you need.
getIcons({
icons: {
Menu,
ArrowRight,
Globe
}
});
```
--------------------------------
### createElement(icon, options?)
Source: https://context7.com/box-icons/boxicons/llms.txt
Programmatically creates an `SVGSVGElement` from an `IconDefinition` with optional rendering options. It provides a fallback for non-browser environments (Node.js/SSR) by returning an object with an `outerHTML` property.
```APIDOC
## `createElement(icon, options?)` — Programmatic SVG element
Creates an `SVGSVGElement` from an `IconDefinition` and optional rendering options. In non-browser environments (Node.js / SSR), returns a minimal object exposing `outerHTML` instead of a real DOM element, making it safe to use in server-side rendering pipelines.
### Parameters
- **icon** (IconDefinition) - Required - The icon component to create an element from.
- **options** (IconOptions) - Optional - Rendering options for the SVG element.
- **options.pack** (string) - Optional - The icon pack ('basic', 'filled', 'brands'). Defaults to 'basic'.
- **options.size** (string | number) - Optional - The size of the icon (e.g., 'xs', 'sm', 'md', 'lg', 'xl', or a pixel value).
- **options.fill** (string) - Optional - The fill color of the icon.
- **options.opacity** (number) - Optional - The opacity of the icon.
- **options.rotate** (number) - Optional - The rotation angle in degrees.
- **options.className** (string) - Optional - CSS classes to apply to the SVG element.
- **options.ariaLabel** (string) - Optional - Accessibility label for the icon.
### Request Example
```javascript
import { createElement, Alarm } from '@boxicons/js';
const alarmIcon = createElement(Alarm, {
pack: 'filled',
size: 'lg',
fill: '#D69E2E',
opacity: 0.85,
rotate: 45,
className: 'alarm-icon',
ariaLabel: 'Alarm icon',
});
document.getElementById('toolbar').appendChild(alarmIcon);
// SSR / Node.js fallback
if (typeof document === 'undefined') {
const ssrIcon = createElement(Alarm, { size: 'sm', fill: 'red' });
console.log(ssrIcon.outerHTML);
}
```
```
--------------------------------
### Advanced getIcons Options
Source: https://github.com/box-icons/boxicons/blob/main/README.md
Customize icon replacement behavior using options like `nameAttr`, `attrs`, `root`, and `inTemplates`. This allows for more flexible integration.
```javascript
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
});
```
--------------------------------
### Template Tags Support
Source: https://github.com/box-icons/boxicons/blob/main/README.md
Enable icon replacement within `` tags by setting `inTemplates: true` in the `getIcons` function options.
```javascript
import { getIcons, Menu, Home } from '@boxicons/js';
getIcons({
icons: { Menu, Home },
inTemplates: true
});
```
```html
```
--------------------------------
### Manual Auto-Mode Control: `observe` and `scanAndReplace`
Source: https://context7.com/box-icons/boxicons/llms.txt
Provides manual control over the auto-mode functionality. `scanAndReplace` performs a one-time DOM scan, while `observe` sets up a `MutationObserver` to handle dynamically added icons.
```APIDOC
## `observe(root?)` and `scanAndReplace(root?)` — manual auto-mode control
`scanAndReplace` performs a one-time DOM scan using all available icons. `observe` sets up a `MutationObserver` that automatically processes any icons added to the DOM after the initial scan. Both functions are exported from `@boxicons/js/auto` for granular control.
```javascript
import { scanAndReplace, observe } from '@boxicons/js/auto';
// One-time replacement of icons already in the DOM
scanAndReplace(document.getElementById('app'));
// Watch for dynamically inserted icons
const observer = observe(document.getElementById('app'));
// Later — dynamically added elements are automatically handled
document.getElementById('app').innerHTML += '';
// → The new element is replaced with its SVG automatically
// Stop observing when no longer needed (e.g., component unmount)
observer.disconnect();
```
```
--------------------------------
### GetIconsOptions
Source: https://github.com/box-icons/boxicons/blob/main/README.md
Reference for the options available when using the `getIcons` function.
```APIDOC
## 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 `` tags |
```
--------------------------------
### `getSizePixels(size)` - Size Preset to Pixel Conversion
Source: https://context7.com/box-icons/boxicons/llms.txt
Converts a named `IconSize` preset (e.g., 'xs', 'lg') to its corresponding numeric pixel value. This is useful for custom rendering logic or layout calculations requiring exact pixel dimensions.
```APIDOC
## `getSizePixels(size)` — size preset to pixel conversion
Converts a named `IconSize` preset to its numeric pixel value. Useful when building custom rendering logic or layout calculations that need exact pixel sizes.
```javascript
import { getSizePixels } from '@boxicons/js';
console.log(getSizePixels('xs')); // → 16
console.log(getSizePixels('sm')); // → 20
console.log(getSizePixels('base')); // → 24
console.log(getSizePixels('md')); // → 36
console.log(getSizePixels('lg')); // → 48
console.log(getSizePixels('xl')); // → 64
console.log(getSizePixels('2xl')); // → 96
console.log(getSizePixels('3xl')); // → 128
console.log(getSizePixels('4xl')); // → 256
console.log(getSizePixels('5xl')); // → 512
```
```
--------------------------------
### Custom Sizing
Source: https://github.com/box-icons/boxicons/blob/main/README.md
Set custom dimensions for icons by using the `data-bx-width` and `data-bx-height` attributes.
```html
```
--------------------------------
### Boxicons Auto-Import Initialization (ESM)
Source: https://context7.com/box-icons/boxicons/llms.txt
Import from `@boxicons/js/auto` in an ESM environment for automatic icon replacement and live observation of DOM changes. You can access and disconnect the `autoObserver` if needed.
```javascript
// ESM — automatic replacement + live observation of the DOM
import '@boxicons/js/auto';
// No further calls needed; icons already replaced and observer running.
// Access the MutationObserver instance to stop watching if needed
import { autoObserver } from '@boxicons/js/auto';
autoObserver?.disconnect();
```
--------------------------------
### createSvgString(icon, options?)
Source: https://context7.com/box-icons/boxicons/llms.txt
Generates a raw SVG markup string for a given icon and options. This method is suitable for templating engines, server-side rendering, or when a DOM element is not required. It supports all `IconOptions` for customization.
```APIDOC
## `createSvgString(icon, options?)` — SVG string generation
Returns a raw SVG markup string for a given icon and options. Ideal for templating engines, server-side rendering, or situations where a real DOM element is not needed. All `IconOptions` are supported, including transformations, fill, opacity, sizing, and accessibility attributes.
### Parameters
- **icon** (IconDefinition) - Required - The icon component to generate SVG markup for.
- **options** (IconOptions) - Optional - Rendering options for the SVG string.
- **options.pack** (string) - Optional - The icon pack ('basic', 'filled', 'brands'). Defaults to 'basic'.
- **options.size** (string | number) - Optional - The size of the icon (e.g., 'xs', 'sm', 'md', 'lg', 'xl', or a pixel value).
- **options.fill** (string) - Optional - The fill color of the icon.
- **options.opacity** (number) - Optional - The opacity of the icon.
- **options.flip** (string) - Optional - Flips the icon horizontally or vertically ('horizontal', 'vertical').
- **options.removePadding** (boolean) - Optional - If `true`, adjusts the `viewBox` to remove default padding.
- **options.className** (string) - Optional - CSS classes to apply to the SVG element.
- **options.style** (string) - Optional - Inline styles to apply to the SVG element.
- **options.ariaLabel** (string) - Optional - Accessibility label for the icon.
### Request Example
```javascript
import { createSvgString, Home } from '@boxicons/js';
// Minimal usage
const basicSvg = createSvgString(Home);
// With full options
const styledSvg = createSvgString(Home, {
pack: 'filled',
size: 'xl',
fill: '#2B6CB0',
opacity: 0.9,
flip: 'horizontal',
removePadding: true,
className: 'nav-icon home-icon',
style: 'display: inline-block;',
ariaLabel: 'Home',
});
// Inject directly into a template string
const html = `${styledSvg}Home`;
// Express / server-side example
app.get('/icon', (req, res) => {
res.setHeader('Content-Type', 'image/svg+xml');
res.send(createSvgString(Home, { size: 'md', fill: 'navy' }));
});
```
```
--------------------------------
### Styling Icons
Source: https://github.com/box-icons/boxicons/blob/main/README.md
Customize icon appearance with attributes for fill color (`data-bx-fill`), opacity (`data-bx-opacity`), and padding removal (`data-bx-remove-padding`).
```html
```
--------------------------------
### Shadow DOM Support
Source: https://github.com/box-icons/boxicons/blob/main/README.md
Integrate Boxicons within Shadow DOM by providing the shadow root as the `root` option to `getIcons`. This ensures encapsulation.
```javascript
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 = `
`;
// Replace icons inside the shadow root
getIcons({
icons: { Menu, Home },
root: shadow
});
}
}
customElements.define('my-component', MyComponent);
```
--------------------------------
### Transformations
Source: https://github.com/box-icons/boxicons/blob/main/README.md
Apply transformations like horizontal or vertical flips, and rotations (in degrees) using `data-bx-flip` and `data-bx-rotate` attributes.
```html
```
--------------------------------
### getIcons(options)
Source: https://context7.com/box-icons/boxicons/llms.txt
Scans the DOM for elements with the `data-bx` attribute and replaces them with corresponding SVGs. It supports tree-shaking by only processing specified icons and offers options for applying default attributes, restricting the scan scope, and processing icons within `` tags.
```APIDOC
## `getIcons(options)` — DOM-based icon replacement
Scans the DOM (or a custom root element) for elements with the `data-bx` attribute and replaces each one with the corresponding SVG. Only the icons explicitly passed in `options.icons` are used, making the call fully tree-shakable. Supports Shadow DOM and `` tags via additional options.
### Parameters
- **options** (object) - Required - Configuration object for `getIcons`.
- **options.icons** (object) - Required - An object where keys are icon names and values are the imported icon components.
- **options.attrs** (object) - Optional - Default visual attributes to apply to all replaced icons (e.g., `fill`, `size`, `className`).
- **options.root** (Element) - Optional - The root DOM element to start the scan from. Defaults to `document`.
- **options.inTemplates** (boolean) - Optional - If `true`, icons within `` tags will also be processed.
### Request Example
```javascript
import { getIcons, Menu, ArrowRight, Globe, LogoGithub } from '@boxicons/js';
getIcons({
icons: { Menu, ArrowRight, Globe, LogoGithub },
attrs: {
fill: '#4A5568',
size: 'md',
className: 'icon',
},
root: document.getElementById('app'),
inTemplates: true,
});
```
### HTML Before
```html
```
### HTML After
```html
```
```
--------------------------------
### Declarative HTML API with Data Attributes
Source: https://context7.com/box-icons/boxicons/llms.txt
Control individual icon attributes directly in HTML using the `data-bx-*` attribute family. This allows for easy customization of icons without writing any JavaScript.
```APIDOC
## Data attributes — declarative HTML API
Individual icon attributes are controlled directly in HTML without writing JavaScript, relying on the `data-bx-*` attribute family parsed by `parseDataAttributes`.
```html
```
```
--------------------------------
### Programmatic SVG Element Creation with createElement
Source: https://context7.com/box-icons/boxicons/llms.txt
Create an `SVGSVGElement` using `createElement` for programmatic control. In non-browser environments, it returns an object with `outerHTML` for SSR compatibility. Customize icons with various options.
```javascript
import { createElement, Alarm } from '@boxicons/js';
// Create a customised SVG element and mount it
const alarmIcon = createElement(Alarm, {
pack: 'filled',
size: 'lg', // 48 px
fill: '#D69E2E',
opacity: 0.85,
rotate: 45,
className: 'alarm-icon',
ariaLabel: 'Alarm icon', // adds role="img", removes aria-hidden
});
document.getElementById('toolbar').appendChild(alarmIcon);
// SSR / Node.js — safe fallback
if (typeof document === 'undefined') {
const ssrIcon = createElement(Alarm, { size: 'sm', fill: 'red' });
console.log(ssrIcon.outerHTML);
// → ''
}
```
--------------------------------
### Create SVG String and Element with Boxicons JS
Source: https://github.com/box-icons/boxicons/blob/main/README.md
Import functions to generate SVG as a string or a DOM element. Customize size and fill color. Appends the created SVG element to the document body.
```javascript
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);
```
--------------------------------
### Core Functions
Source: https://github.com/box-icons/boxicons/blob/main/README.md
Reference for the core functions available in the Boxicons JavaScript library.
```APIDOC
## 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 |
```
--------------------------------
### Manual Boxicons Auto-Mode Control
Source: https://context7.com/box-icons/boxicons/llms.txt
Use `scanAndReplace` for a one-time DOM scan or `observe` to set up a `MutationObserver` for dynamically added icons. Both are exported from `@boxicons/js/auto` for granular control.
```javascript
import { scanAndReplace, observe } from '@boxicons/js/auto';
// One-time replacement of icons already in the DOM
scanAndReplace(document.getElementById('app'));
// Watch for dynamically inserted icons
const observer = observe(document.getElementById('app'));
// Later — dynamically added elements are automatically handled
document.getElementById('app').innerHTML += '';
// → The new element is replaced with its SVG automatically
// Stop observing when no longer needed (e.g., component unmount)
observer.disconnect();
```
--------------------------------
### Boxicons `getSizePixels` Function
Source: https://context7.com/box-icons/boxicons/llms.txt
Converts named icon size presets (e.g., 'xs', 'lg') to their corresponding pixel values. Useful for custom rendering logic or layout calculations requiring exact pixel dimensions.
```javascript
import { getSizePixels } from '@boxicons/js';
console.log(getSizePixels('xs')); // → 16
console.log(getSizePixels('sm')); // → 20
console.log(getSizePixels('base')); // → 24
console.log(getSizePixels('md')); // → 36
console.log(getSizePixels('lg')); // → 48
console.log(getSizePixels('xl')); // → 64
console.log(getSizePixels('2xl')); // → 96
console.log(getSizePixels('3xl')); // → 128
console.log(getSizePixels('4xl')); // → 256
console.log(getSizePixels('5xl')); // → 512
```
--------------------------------
### Data Attributes
Source: https://github.com/box-icons/boxicons/blob/main/README.md
Reference for the data attributes that can be used to customize icons directly in HTML.
```APIDOC
## 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) |
```
--------------------------------
### Create Icon Element
Source: https://github.com/box-icons/boxicons/blob/main/README.md
Use `createElement` to generate an SVG HTMLElement for a specific icon. This element can then be appended to the DOM.
```javascript
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);
```
--------------------------------
### `buildTransform(flip?, rotate?)` - SVG Transform Builder
Source: https://context7.com/box-icons/boxicons/llms.txt
Generates an SVG `transform` attribute string based on provided flip and rotate options. It returns `undefined` if no transformation is specified and is internally used by `createSvgString` but also exportable for custom pipelines.
```APIDOC
## `buildTransform(flip?, rotate?)` — SVG transform builder
Generates an SVG `transform` attribute string from flip and rotate options. Returns `undefined` when no transformation is requested. Consumed internally by `createSvgString` but also exported for use in custom rendering pipelines.
```javascript
import { buildTransform } from '@boxicons/js';
buildTransform('horizontal'); // → 'scale(-1,1)'
buildTransform('vertical'); // → 'scale(1,-1)'
buildTransform(undefined, 45); // → 'rotate(45)'
buildTransform(undefined, '90deg'); // → 'rotate(90)' (strips "deg" suffix)
buildTransform('horizontal', 90); // → 'scale(-1,1) rotate(90)'
buildTransform(); // → undefined (no transform applied)
```
```
--------------------------------
### Basic Boxicons HTML Declarations
Source: https://context7.com/box-icons/boxicons/llms.txt
Control individual icon attributes directly in HTML using the `data-bx-*` attribute family. This method requires no JavaScript for basic icon rendering.
```html
```
```html
```
```html
```
```html
```
```html
```
```html
```
```html
```
```html
```
```html
```
```html
```
--------------------------------
### DOM-based Icon Replacement with getIcons
Source: https://context7.com/box-icons/boxicons/llms.txt
Use `getIcons` to scan the DOM for elements with the `data-bx` attribute and replace them with corresponding SVGs. Specify icons and optional attributes for customization. Supports Shadow DOM and `` tags.
```javascript
import { getIcons, Menu, ArrowRight, Globe, LogoGithub } from '@boxicons/js';
// Replace all matching elements found in the document
getIcons({
icons: { Menu, ArrowRight, Globe, LogoGithub },
// Apply default visual attributes to every replaced icon
attrs: {
fill: '#4A5568',
size: 'md', // 36 px
className: 'icon',
},
// Optional: restrict scan to a specific subtree
root: document.getElementById('app'),
// Optional: also process icons inside tags
inTemplates: true,
});
// HTML before:
//
//
//
//
// HTML after (each is replaced with the corresponding