JS | Solar Icons

Vanilla JavaScript library for dynamic DOM injection of Solar Icons using lightweight ASTs.

npm install @solar-icons/js@2.0.0-beta.0

Using a CDN (No Bundler)

Since Solar Icons contains exactly 7,476 icons across different styles, a traditional global script (UMD) would be massive. Instead, the package is distributed natively as ES Modules (ESM).

You can use it directly in the browser using a modern CDN like esm.sh:

<!DOCTYPE html>
<html>
    <body>
        <i data-solar="heart-bold"></i>
        <span data-solar="accessibility-line-duotone"></span>

        <script type="module">
            // Import only the icons you need, directly from the CDN!
            import {
                createIcons,
                HeartBoldIcon,
                AccessibilityLineDuotoneIcon,
            } from 'https://esm.sh/@solar-icons/js@2.0.0-beta.0'

            createIcons({
                icons: {
                    HeartBoldIcon,
                    AccessibilityLineDuotoneIcon,
                },
            })
        </script>
    </body>
</html>

We strongly recommend using https://esm.sh/@solar-icons/js@<version> rather than @latest to prevent unexpected breaking changes in production.

What you can accomplish:

Replace DOM placeholders with Solar Icons dynamically at runtime
Pass CSS properties, stroke weights, and colors dynamically
Build applications without complex framework setups or VDOM overhead

This package uses a highly performant, Lucide-style AST approach to build DOM elements natively via document.createElementNS(), avoiding any slow DOMParser or innerHTML injections.

Basic Usage

Include placeholders in your HTML. Use the data-solar attribute with the icon's kebab-case name and style:

<i data-solar="heart-bold"></i> <span data-solar="accessibility-line-duotone"></span>

Then, initialize them in your JavaScript by passing the imported icons to createIcons:

import { createIcons, HeartBoldIcon, AccessibilityLineDuotoneIcon } from '@solar-icons/js'

// This replaces the <i> and <span> tags with fully rendered <svg> elements
createIcons({
    icons: {
        HeartBoldIcon,
        AccessibilityLineDuotoneIcon,
    },
})

Styling and Attributes

You can style the icons directly by passing attributes to the placeholder element.

Custom Attributes (Recommended)

Just like our React or Vue packages, you can pass custom attributes directly to the placeholder. These are automatically mapped to inline styles on the injected SVG:

<i
    data-solar="home-angle-bold-duotone"
    size="48"
    color="red"
    secondary-color="blue"
    secondary-opacity="0.6"
    stroke-width="0.5"></i>

CSS Classes and Global Styling

Any classes placed on the placeholder element will be preserved and merged. Furthermore, the injected SVG automatically receives both a generic `solar` class and a specific class like `solar-heart-bold`.

<i data-solar="heart-bold" class="text-red-500 my-custom-class"></i>

This generates:

<svg class="solar solar-heart-bold text-red-500 my-custom-class" ...></svg>

You can target the `solar` class in your global CSS to define default sizing or stroke widths:

.solar {
    /* Default styles for all Solar Icons */
    width: 24px;
    height: 24px;
    stroke-width: 1.5;
}

API Reference

`createIcons(options)`

icons (Object): Map of PascalCase icon names to their imported AST structures. Required.
nameAttr (string): The HTML attribute used to identify placeholders. Defaults to 'data-solar'.
attrs (Object): Additional attributes to apply to every injected SVG. This is fully typed and supports custom Solar properties. Note: CSS classes provided here are merged, not overwritten. The default solar classes are preserved.

import { createIcons, HeartBoldIcon } from '@solar-icons/js'

createIcons({
    icons: { HeartBoldIcon },
    nameAttr: 'data-custom-icon', // Optional
    attrs: {
        // Classes are safely appended alongside "solar solar-heart-bold"
        class: 'my-custom-icon-class',

        // Fully typed properties that map directly to SVG inline styles
        size: 48,
        color: '#ef4444',
        'secondary-color': '#fca5a5',
        'secondary-opacity': 0.8,
        'stroke-width': 2,
    },
})

Because this package dynamically constructs DOM nodes, tree-shaking is fully supported. Only the icons you explicitly import and pass to createIcons will be included in your final bundle.

JS