[](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements)
[](https://bundlephobia.com/package/@components-1812/svg-isolate)
[](https://github.com/components-1812/svg-isolate/stargazers)
# SVG Isolate Custom Element
## Features
- ๐ **Shadow DOM isolation** โ SVG styles and IDs are scoped to the component. No conflicts with the rest of the page.
- ๐ฆ **Smart caching** โ LRU in-memory cache with deduplication. Same URL fetched once, shared across all instances. Configurable by item count and byte size limit.
- ๐ผ๏ธ **srcset support** โ serve different SVG files based on the component's rendered width, just like native ``.
- โก **Loading strategies** โ `eager`, `defer`, `idle`, and `lazy` (via `IntersectionObserver`).
- ๐ **Base URL** โ resolve src against a configurable base path or CDN URL. Set per-element or globally via defaults.
- ๐จ **Flexible styling** โ inject CSS into the shadow DOM globally via `define()` or per-instance via `componentStyles`.
- ๐งน **Optional sanitization** โ plug in any sanitizer (e.g. DOMPurify) to clean SVG nodes before rendering.
- ๐ **Responsive** โ automatic candidate swapping on resize via `ResizeObserver`.
- ๐งฉ **Extensible** โ designed to be subclassed. Override fetching, sanitization, rendering, or defaults.
## Examples
- [**Examples**](https://components-1812.github.io/svg-isolate/)
- [**Codepen Examples**](https://codepen.io/collection/YwZMEz)
- [id collision](https://codepen.io/FrancoJavierGadea/pen/zxoPqwK)
- [loading strategies](https://codepen.io/FrancoJavierGadea/pen/ogYoxWG)
- [base](https://codepen.io/FrancoJavierGadea/pen/VYmrapr)
- [cache visualization](https://codepen.io/FrancoJavierGadea/pen/jEVaqBj)
- [no cache](https://codepen.io/FrancoJavierGadea/pen/ByQmKRv)
- [sanitize](https://codepen.io/FrancoJavierGadea/pen/jEVaqmg)
- [state attributes](https://codepen.io/FrancoJavierGadea/pen/dPOZMRZ)
- [srcset and responsive](https://codepen.io/FrancoJavierGadea/pen/PwbONjy)
## Contents
- [Installation](#installation)
- [Usage](#usage)
- [Custom definition](#custom-definition)
- [Instance styles](#instance-styles)
- [Default styles](#default-styles-bundle)
- [`width` and `height`](#width-and-height)
- [Base URL](#base-url)
- [Cache](#cache)
- [Loading Strategies](#loading-strategies)
- [srcset & Responsive](#srcset--responsive)
- [Sanitize](#sanitize)
- [Styling the inner SVG](#styling-the-inner-svg)
- [Attributes](#attributes)
- [Events](#events)
## Installation
### NPM
```bash
npm install @components-1812/svg-isolate
```
### CDN
#### Auto-define (recommended)
Loads the bundle and registers `` automatically with default styles included.
```html
```
#### Manual definition
Use this if you need a custom tag name or want to provide your own styles.
```html
```
### Available files
| File | jsdelivr | unpkg |
| -------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| Bundle (recommended) | [link](https://cdn.jsdelivr.net/npm/@components-1812/svg-isolate/dist/index.bundle.min.js) | [link](https://unpkg.com/@components-1812/svg-isolate/dist/index.bundle.min.js) |
| SVGIsolate.js | [link](https://cdn.jsdelivr.net/npm/@components-1812/svg-isolate/dist/SVGIsolate.min.js) | [link](https://unpkg.com/@components-1812/svg-isolate/dist/SVGIsolate.min.js) |
| SVGIsolate.css | [link](https://cdn.jsdelivr.net/npm/@components-1812/svg-isolate/dist/SVGIsolate.min.css) | [link](https://unpkg.com/@components-1812/svg-isolate/dist/SVGIsolate.min.css) |
## Usage
Import the component in a client-side script file:
```js
import "@components-1812/svg-isolate";
```
> This loads the bundle, auto-defines the custom element as ``, and applies the default styles via `adoptedStyleSheets`.
```html
```
## Custom definition
If you need to register the element under a different tag name or inject custom styles into its shadow DOM, use `SVGIsolate.define()` directly instead of the auto-import.
#### Via `adoptedStyleSheets`
Best for programmatically constructed styles or when working with a build system that produces `CSSStyleSheet` objects.
```js
import SVGIsolate from "@components-1812/svg-isolate/SVGIsolate.js";
const sheet = new CSSStyleSheet();
sheet.replaceSync(`:host { display: inline-block; }`);
SVGIsolate.define("custom-svg-isolate", { adopted: [sheet] });
```
#### Via raw CSS string
Best for inlining styles directly without an external file.
```js
import SVGIsolate from "@components-1812/svg-isolate/SVGIsolate.js";
SVGIsolate.define("custom-svg-isolate", {
raw: [`:host { display: inline-block; }`],
});
```
#### Via external stylesheet
Best for loading styles from a CSS file at runtime. URLs are resolved against `document.baseURI`, so relative paths are accepted.
```js
import SVGIsolate from "@components-1812/svg-isolate/SVGIsolate.js";
SVGIsolate.define(null, { links: ["/path/to/styles.css"] });
```
All three options can be combined in a single `define()` call:
```js
SVGIsolate.define("custom-svg-isolate", {
adopted: [sheet],
raw: [":host { display: block; }"],
links: ["/path/to/styles.css"],
});
```
Duplicate entries are ignored automatically โ adding the same URL or `CSSStyleSheet` object twice has no effect.
## Instance styles
Every `` element exposes a `componentStyles` property โ a `ComponentStyles` instance that controls the styles injected into its shadow DOM. You can add or replace styles on a specific element at any time without affecting other instances.
### Adding styles
`componentStyles.add()` accepts the same `{ links, adopted, raw }` shape as `define()`. Chain `.apply()` to re-render the shadow DOM styles immediately.
```js
const el = document.querySelector("svg-isolate");
el.componentStyles
.add({ raw: [`:host { outline: 2px solid red; }`] })
.apply();
```
Duplicate entries are ignored โ adding the same URL or raw string twice has no effect.
### Targeting SVG internals
CSS injected this way lives inside the shadow root, so it can reach the SVG elements directly:
```js
document.querySelector('svg-isolate[sanitize]')
.componentStyles
.add({
raw: `
circle { fill: #5f000d; }
rect { fill: #070070; }
text { fill: #c5b800; font-family: serif; }
`,
})
.apply();
```
### Working with the collections directly
Each style type is a `StyleCollection` instance and can be manipulated directly before calling `.apply()`:
```js
const { raw, links, adopted } = el.componentStyles;
// check what's already registered
console.log(raw.size); // number of raw CSS strings
console.log(links.size); // number of external stylesheets
// check if a specific entry exists
links.has("https://example.com/theme.css");
// iterate over current entries
for (const url of links) {
console.log(url);
}
// remove everything from one collection and replace it
raw.clear();
raw.add([`circle { fill: hotpink; }`]);
el.componentStyles.apply();
```
### Adding an external stylesheet to one instance
```js
el.componentStyles.add({ links: ["/themes/dark.css"] }).apply();
```
The `ready-links` event fires once the stylesheet has loaded.
### Replacing all styles
Call `.clear()` before `.add()` to discard everything and start fresh:
```js
el.componentStyles
.clear()
.add({ raw: [`:host { background: #000; }`] })
.apply();
```
> **Note:** `componentStyles` is per-instance. Changes made to one element do not affect other `` elements on the page, even if they share the same `src`.
## Default styles (bundle)
When loaded via the auto-import bundle, ships with these default host styles:
```css
:host {
position: relative;
display: inline-block;
margin: 0;
padding: 0;
width: 100%;
height: 100%;
contain: size;
overflow: hidden;
}
:host svg {
display: block;
width: 100%;
height: 100%;
}
```
From: [/src/SVGIsolate.css](/src/SVGIsolate.css)
The most important of these is `contain: size` โ it prevents the component from triggering
layout recalculations in its parent (particularly relevant inside `flex` and `grid` containers,
where an unsized inline element can cause repeated reflows).
If you register the component manually via `SVGIsolate.define()`, none of these styles are applied automatically.
You can inject them (or a modified version) via the `adopted`, `raw`, or `links` options โ see [Custom definition](#custom-definition).
Note that `width: 100%; height: 100%` means the component sizes itself to its container โ
if the container has no explicit dimensions, the component collapses to zero.
Use the [`width` and `height` attributes](#width-and-height) or size the container from CSS.
To override the defaults on a specific instance without touching others, use `componentStyles` directly:
```js
el.componentStyles
.clear()
.add({ raw: [`:host { display: block; width: 300px; height: 300px; }`] })
.apply();
```
See [Instance styles](#instance-styles) for the full API.
## `width` and `height`
Sets `style.width` and `style.height` on the `` host element directly.
```html
```
```js
el.width = "50%";
el.height = "120px";
```
Accepts any valid CSS length value. Equivalent to setting `style.width` / `style.height` inline โ useful when you want to control dimensions declaratively via HTML rather than in your stylesheet.
## Base URL
You can provide a `base` attribute to resolve the `src` URL against a specific base path rather than the document's base URI.
The `base` is always a fixed URL to which the `src` is concatenated. If `base` is relative, it is resolved against `document.baseURI`. Then, if `src` is also relative, its resolved path is appended to the `base`.
The resulting URL follows this structure:
```txt
//?#
```
- The default value of `base` is `"/"`.
- If `src` is an absolute URL, `base` is ignored entirely and `src` is used as-is.
- The resolution logic is handled internally by the static method `SVGIsolate.resolveSource(src, base)`
### Usage
```html
```
```js
el.base = "/assets";
```
### Setting a default base
To apply a fixed `base` to all instances of a custom element, set it in `SVGIsolate.defaults.base` before calling `define()`:
```js
class BootstrapIcon extends SVGIsolate {
static defaults = {
...super.defaults,
base: "https://raw.githubusercontent.com/twbs/icons/refs/heads/main/icons",
};
}
BootstrapIcon.define("bootstrap-icon", {
links: [
"https://cdn.jsdelivr.net/npm/@components-1812/svg-isolate@0.0.2/dist/SVGIsolate.min.css",
],
});
```
Now every `` resolves `src` against that CDN path without needing `base` on each element:
```html
```
### Examples
Here are a few representative examples of how different inputs are resolved (assuming a document URI of `http://127.0.0.1:3000/docs/examples/base-test/`):
| `src` | `base` | Resolved URL | Description |
| :----------------------------------- | :------------------------ | :--------------------------------------------------------------------------- | :-------------------------------------------------- |
| `https://raw.example.com/circle.svg` | `/docs` | `https://raw.example.com/circle.svg` | Absolute URL `src`, `base` is ignored |
| `/assets/circle.svg` | `/docs` | `http://127.0.0.1:3000/docs/assets/circle.svg` | Root-relative `src` treated relative to `base` path |
| `../../../assets/circle.svg` | `/docs` | `http://127.0.0.1:3000/docs/assets/circle.svg` | Root-relative nested `src` with path `base` |
| `/0-circle.svg` | `https://raw.example.com` | `https://raw.example.com/0-circle.svg` | Root-relative `src` with absolute domain `base` |
| `circle.svg` | `/` | `http://127.0.0.1:3000/docs/examples/base-test/circle.svg` | Relative `src` with default `base` |
| `assets/circle?w=150#svg` | `/docs` | `http://127.0.0.1:3000/docs/docs/examples/base-test/assets/circle?w=150#svg` | With query params and hash |
## Cache
By default, `` caches every SVG source **in memory** after the first fetch, so subsequent requests for the same URL are served instantly without hitting the network.
### Disabling per instance
Use the `no-cache` attribute:
```html
```
Or via the `.useCache` property:
```js
const svg = document.querySelector("svg-isolate");
svg.useCache = false;
```
### Disabling by default
To disable caching for all instances:
```js
SVGIsolate.defaults.useCache = false;
```
### Disabling cache entirely
To disable the cache system completely โ no cache is created at `define()` time, `.useCache` always returns `false` and cannot be set to `true`:
```js
SVGIsolate.CACHE_ENABLED = false;
```
Must be set **before** calling `SVGIsolate.define()`.
### Limits & Eviction
By default, the cache holds up to `100` entries with no maximum cumulative byte size limit (`Infinity`). When limits are reached, the least recently used entry is evicted before adding the new one (LRU):
```js
// Evict after 50 items
SVGIsolate.CACHE_MAX_ENTRIES = 50;
// Evict after 10 Megabytes of accumulated SVG strings
SVGIsolate.CACHE_MAX_SIZE = '10mb'; // Also accepts '500kb', '1.5g', or raw bytes like 5000000
```
Both must be set **before** calling `SVGIsolate.define()`.
> [!NOTE]
> The size values are parsed **case-insensitively** (e.g., `'1mb'` is identical to `'1MB'`) and represent sizes in **bytes** rather than bits (e.g., `'1MB'` or `'1mb'` is parsed as exactly $1,024^2$ bytes, representing 1 Megabyte, not a Megabit).
### Shared cache
The cache is shared across all instances of the same component class. Two `` elements pointing to the same `src` will only trigger one fetch โ the second reuses the cached result.
### Accessing the cache directly
```js
SVGIsolate.CACHE.clear(); // clear all entries
SVGIsolate.CACHE.delete(src); // remove a specific entry
SVGIsolate.CACHE.has(src); // check if a src is cached
SVGIsolate.CACHE.values; // Map with all cached entries
```
#### Preloading
You can manually populate the cache before any component renders:
```js
await SVGIsolate.CACHE.fetchSVG("/assets/icon.svg");
```
This is useful for preloading critical SVGs during app initialization so the first render is instant.
## Loading Strategies
`` supports four loading strategies controlled by the `loading` attribute.
### Eager (default)
Fetches the SVG immediately when the element connects to the DOM.
```html
```
### Defer
Waits for the `DOMContentLoaded` event before fetching. Useful when the SVG is not critical for the initial render.
```html
```
### Idle
Fetches during the browser's idle time using `requestIdleCallback`. Falls back to `defer` if the browser does not support it.
```html
```
> **Note:** `requestIdleCallback` is not supported in Safari stable (May 2026). The component automatically falls back to `defer` in that case.
### Lazy
Fetches the SVG only when the element enters the viewport, using `IntersectionObserver`. Ideal for SVGs below the fold.
```html
```
You can control when the load is triggered with `lazy-margin` and `lazy-threshold`:
```html
```
- **`lazy-margin`** โ extends the viewport boundary before triggering the load. Accepts any valid CSS margin value (e.g. `200px`, `10%`).
- **`lazy-threshold`** โ percentage of the element that must be visible before triggering (0 to 1). Default is `0`.
### Setting a default strategy
```js
SVGIsolate.defaults.loading = "lazy";
```
## srcset & Responsive
`` supports `srcset` to serve different SVG files depending on the component's rendered **width**, similar to how native `` works.
### Basic usage
Each candidate requires a width descriptor (`w`) representing the intrinsic width the SVG was designed for.
If no descriptor is provided, the candidate defaults to `0w`.
```html
```
### src and srcset
`src` and `srcset` are mutually exclusive. If `srcset` is present, `src` is ignored entirely โ `srcset` always takes priority.
```html
```
This also applies when attributes change dynamically โ if `srcset` is set at any point, `src` stops being considered until `srcset` is removed.
```js
const el = document.querySelector("svg-isolate");
el.srcset = "icon-300.svg 300w, icon-600.svg 600w"; // src ignored from now on
el.srcset = null; // src is considered again
```
### Candidate selection algorithm
The component measures its own rendered width and picks the smallest candidate whose intrinsic width covers it:
```
component width: 450px
candidates: 300w, 600w, 900w
โ 300w < 450 โ does not cover
โ 600w โฅ 450 โ covers โ โ selected
```
If the component is wider than all candidates, the **largest** is used as a fallback.
The selection runs once on connect, and again on every resize if `responsive` is enabled.
### Responsive
By default the component resolves the candidate once on connect. Add the `responsive` attribute to keep listening for size changes and swap the SVG automatically on resize:
```html
```
Swaps are debounced to avoid excessive fetches during resize. Previously loaded candidates are served from the in-memory cache instantly.
### Setting defaults
```js
SVGIsolate.defaults.responsive = true;
```
## Sanitize
> [!WARNING]
> **XSS Risk on Untrusted SVGs:**
> If you are loading SVGs from untrusted user uploads or external user-generated sources, **always enable the `sanitize` attribute** and configure a secure sanitizer like `DOMPurify`.
>
> While static `