Registry / web-framework / vue-shadow-dom

vue-shadow-dom

JSON →
library4.2.0jsnpmunverified

vue-shadow-dom is a JavaScript library providing robust Shadow DOM support for Vue 3 applications, currently stable at version 4.2.0. It allows developers to leverage the browser's native Shadow DOM capabilities directly within Vue components, enabling strict encapsulation of styles and markup. The library achieves this through the provision of a Vue plugin, a `v-shadow` directive, and dedicated `<shadow-root>` and `<shadow-style>` components. While there isn't a stated fixed release cadence, updates tend to align with major Vue ecosystem changes or feature enhancements. A key differentiator is its direct, declarative API for Shadow DOM usage, avoiding complex manual DOM manipulations, and its comprehensive support for various module environments including ESM, CommonJS, and UMD builds, catering to both bundler-driven and browser-only setups. Notably, versions 2.0 and above are specifically designed for Vue 3, while v1.x targets Vue 2.

npm install vue-shadow-dom
INSTALL
IMPORT
SIG · VUE-SHADOW-DOM
V
vue-shadow-dom
web-frameworkjavascriptv4.2.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

shadow
import shadow from 'vue-shadow-dom'
import { shadow } from 'vue-shadow-dom'
This is the default export representing the Vue plugin instance. For CommonJS environments, `const shadow = require('vue-shadow-dom')` can be used directly or specific CJS build paths like `'vue-shadow-dom/dist/shadow.cjs.cjs'`.
ShadowRootExpose
import type { ShadowRootExpose } from 'vue-shadow-dom'
Used for TypeScript users to type the exposed `shadow_root` property when accessing the native ShadowRoot instance from a `<shadow-root>` component ref.

Demonstrates initializing the `vue-shadow-dom` plugin, using the `<shadow-root>` component with custom tag and abstract prop, applying encapsulated styles with `<shadow-style>`, and accessing the native ShadowRoot instance via a ref for direct DOM interaction.

import { createApp, ref, defineComponent } from 'vue'; import shadow, { type ShadowRootExpose } from 'vue-shadow-dom'; const MyShadowComponent = defineComponent({ template: ` <div style="border: 1px solid blue; padding: 10px; margin: 20px;"> <h2>Component Host</h2> <p>Content outside the shadow root. Styles here will leak unless encapsulated.</p> <shadow-root ref="shadowRef" tag="section" abstract> <template #default> <shadow-style> p { color: green; font-weight: bold; } h3 { color: darkred; } button { background-color: lightblue; padding: 8px; border: none; cursor: pointer; } </shadow-style> <h3>Shadow Root Content</h3> <p>This paragraph should be green and bold inside the shadow DOM.</p> <button @click="logShadowRoot">Log Shadow Root</button> </template> </shadow-root> <p>This paragraph is outside the shadow root.</p> </div> `, setup() { const shadowRef = ref<ShadowRootExpose | null>(null); const logShadowRoot = () => { if (shadowRef.value && shadowRef.value.shadow_root) { console.log('Shadow Root Instance:', shadowRef.value.shadow_root); // You can interact with the native ShadowRoot object directly const pElement = shadowRef.value.shadow_root.querySelector('p'); if (pElement) { console.log('Paragraph inside shadow root:', pElement.textContent); } } else { console.warn('ShadowRoot instance not available yet.'); } }; return { shadowRef, logShadowRoot }; }, }); const app = createApp(MyShadowComponent); app.use(shadow); app.mount('#app'); // To run this, you would typically have an index.html like: // <div id="app"></div>
Debug
Known issues
breakingVersion 2.0 and higher of `vue-shadow-dom` are exclusively built for Vue 3. Attempting to use these versions with Vue 2 applications will result in runtime errors due to significant API changes.
fix
For Vue 2 projects, you must install `vue-shadow-dom@1` using `npm i vue-shadow-dom@1`. Always verify your project's Vue version aligns with the compatible library version.
affects: >=2.0.0
gotchaUsing the `abstract` prop on `<shadow-root>` attaches the shadow root directly to the host element. This makes other external sibling HTML tags within the same host element unavailable or unrenderable inside the Shadow DOM, which can lead to unexpected layout or missing content.
fix
Carefully consider the implications of `abstract`. If you need sibling content to render alongside the shadow root or to be styled by global styles, avoid using `abstract`. The default behavior without `abstract` creates an intermediate `div` for the shadow root, allowing siblings to coexist.
affects: >=2.0.0
gotchaImporting the incorrect distribution file (e.g., a bundler-specific ESM build directly in a browser without a module loader, or a UMD build in a modern bundler setup) can cause module resolution failures or runtime errors.
fix
Consult the 'Files' section in the `vue-shadow-dom` README. Ensure you are importing the correct build artifact for your specific environment: `shadow.esm-bundler.mjs` for packaging tools, `shadow.esm-browser.mjs` for browser ESM, `shadow.global.js` for UMD, and `shadow.cjs.cjs` or the main `vue-shadow-dom` package for Node.js CommonJS.
affects: >=1.0.0
Errors
Common errors & fixes
Failed to resolve component: shadow-root
The `vue-shadow-dom` plugin has not been correctly registered with the Vue application instance, meaning its components and directives are not globally available.
fix
After creating your Vue application with `createApp()`, ensure you register the plugin by calling `app.use(shadow)` before mounting the application, e.g., `const app = createApp(MyRootComponent); app.use(shadow); app.mount('#app');`
TypeError: app.use is not a function
This error typically indicates that `app` is not a valid Vue 3 application instance. This can happen if you are using Vue 2's `new Vue()` API instead of Vue 3's `createApp()` or if `app` is otherwise undefined.
fix
Confirm that your application entry point uses `createApp()` to initialize your Vue 3 application. If you are targeting Vue 2, you must use `vue-shadow-dom@1` and its corresponding initialization method for Vue 2 plugins.
Upgrade
Version history
4.2.0latest on npm
Audit
Dependencies
vuerequiredPeer dependency, required for Vue 3 applications (>=v2.0 of this library).
Agent activity
14 hits · last 30 days
node
12
Amazon
1
OpenAI (training)
1
Resources
vue-shadow-dom — npm install vue-shadow-dom · libregistry