API Reference

Installation

npm

npm install @profpowell/json-viewer

Then in your module:

import '@profpowell/json-viewer'   // side-effect import: defines <json-viewer>
// or
import { JsonViewer } from '@profpowell/json-viewer'
customElements.define('my-viewer', JsonViewer)

CDN

<script type="module" src="https://unpkg.com/@profpowell/json-viewer"></script>

No bundler

Drop dist/json-viewer.js next to your HTML and reference it directly:

<script type="module" src="./json-viewer.js"></script>
<json-viewer expanded="2"></json-viewer>

Attributes

All attributes are observed: changing them after the element is connected triggers a re-render.

Properties

Methods

.expand(matcher) / .collapse(matcher)

Open or close every rendered container whose path matches matcher.

.expandAll() / .collapseAll()

Open or close every currently-rendered container.

.search(query, options?)

Returns a navigable iterator over matches.

const it = viewer.search('error', { regex: false, caseSensitive: false })
it.count            // total matches
it.current?.path    // path of the focused match, or undefined
it.next()           // advance + return { value, done }
it.prev()           // step back
// also iterable: for (const m of viewer.search('foo')) { ... }

The search walks an internal record array built from .data, not the DOM. Only the ancestors of the focused match are expanded — never the whole tree. Only the focused match is wrapped in <mark>.

Options:

.entryAt(path)

Returns { key, value } for any path, including Map and Set entries where the key isn't a string. For object/array paths, key is the last segment; for Map entries it's the original key object (reference-equal to what you put in); for Set entries it's the integer index.

const adaKey = { id: 1 }
const cache = new Map([[adaKey, { hits: 42 }]])
viewer.data = { cache }
const entry = viewer.entryAt('cache@0')
entry.key === adaKey   // true — reference preserved
entry.value.hits       // 42

.copy(text?)

Writes to the clipboard. With no argument, copies a BigInt-safe JSON snapshot of .data. With an argument, copies that string verbatim. Returns a Promise.

await viewer.copy()                    // full BigInt-safe JSON
await viewer.copy(viewer.entryAt('users[0]').value.email)

Events

Both events bubble and are composed: true so they cross the Shadow DOM boundary.

Path grammar

Paths are flat strings. The grammar:

Globs:

CSS custom properties

Public theme contract. Each token resolves through a three-level fallback chain:

var(--json-viewer-FOO, var(--vb-FOO, light-dark(LIGHT, DARK)))

Set --json-viewer-* for direct overrides, set --vb-* at the page level for ecosystem-wide theming, or leave both unset for the built-in light-dark() defaults.

CSS parts

Use ::part() to target inner regions for layout-level customization:

Example: borderless embed

json-viewer::part(toolbar) { display: none; }
json-viewer { border: none; }

Examples

Set data after fetching

const viewer = document.querySelector('json-viewer')
viewer.data = await fetch('/api/me').then(r => r.json())

React to clicks

viewer.addEventListener('json-viewer:keyclick', (e) => {
  console.log('clicked', e.detail.path, '=', e.detail.value)
})

Expand specific paths after a search miss

const it = viewer.search('errorCode')
if (it.count === 0) {
  viewer.expand('**.errors')   // expose error sections so a follow-up search hits them
}

Theme a single instance

<json-viewer style="--json-viewer-accent: #ff5722; --json-viewer-radius: 0">
</json-viewer>