README.md

A Web Component to visualize JSON data in a tree view

---

• Installation
  • From CDN
  • From NPM
• Usage
  • Attributes
  • Properties
  • Methods
  • CSS Parts
  • CSS custom properties
  • Basic Usage
  • Load the JSON dynamically
  • Basic interactions
  • Custom renderer
• Demo

Installation

From CDN

The package contains a bundled version of the component which includes also the Lit library. It can be useful in case you want to import the package using a CDN.

<script src="https://unpkg.com/@alenaksu/[email protected]/dist/json-viewer.bundle.js"></script>

From NPM

Install the component through NPM:

npm i @alenaksu/json-viewer

Import the package to your project, this way the component will be automatically defined in the custom elements registry with its default tag name json-viewer.

import '@alenaksu/json-viewer';

If you want to extend the component or if you just need to use it in scoped registries with a different tag name, then you can import the component class from the package:

import { JsonViewer } '@alenaksu/json-viewer/JsonViewer.js';

class MyJsonViewer extends JsonViewer {
    ...
}

customElements.define('my-json-viewer', MyJsonViewer);

---

Usage

<json-viewer></json-viewer>

Attributes

• data - the string representation of JSON object to load

Properties

• data - get/set the JSON object

Methods

• filter (regexOrPath: RegExp|string) => void | Maintains only the nodes that match the given criteria
• resetFilter () => void | Clear the filter
• expand (regexOrPath: RegExp|string) => void | Expand all the nodes that match the given criteria
• expandAll () => void | Alias for expand('**')
• collapse (regexOrPath: RegExp|string) => void | Collapse all the nodes that match the given criteria
• collapseAll () => void | Alias for collapse('**')
• search (regexOrPath: RegExp|string) => Iterator | Return and iterator with which is possible to go through all the matched nodes. It scrolls the page to the node and highlights it.

CSS Parts

• object - The object wrapper element.
• property - The wrapper element of a property.
• key - The key element of a property.
• primitive - The primitive value.
• primitive--string - Applied when the primitive is a string.
• primitive--number - Applied when the primitive is a number.
• primitive--boolean - Applied when the primitive is a boolean.
• primitive--null - Applied when the primitive is a null.
• preview - The value preview of a property.
• highlight - The highlighted value.

CSS custom properties

The appearance of the component can be modified by changing the CSS custom properties

json-viewer {
    /* Background, font and indentation */
    --background-color: #2a2f3a;
    --color: #f8f8f2;
    --font-family: Nimbus Mono PS, Courier New, monospace;
    --font-size: 1rem;
    --line-height: 1.2rem;
    --indent-size: 0.5em;
    --indentguide-size: 1px;
    --indentguide-style: solid;
    --indentguide-color: #333;
    --indentguide-color-active: #666;
    --indentguide: var(--indentguide-size) var(--indentguide-style) var(--indentguide-color);
    --indentguide-active: var(--indentguide-size) var(--indentguide-style) var(--indentguide-color-active);
    --outline-color: #e0e4e5;
    --outline-width: 1px;
    --outline-style: dotted;

    /* Types colors */
    --string-color: #a3eea0;
    --number-color: #d19a66;
    --boolean-color: #4ba7ef;
    --null-color: #df9cf3;
    --property-color: #6fb3d2;

    /* Collapsed node preview */
    --preview-color: #deae8f;

    /* Search highlight color */
    --highlight-color:  #c92a2a;
}

Basic Usage

Put the JSON inside the element

<json-viewer>
    { "quiz": { "sport": { "q1": { "question": "Which one is correct team name in NBA?", "options": [ "New York Bulls",
    "Los Angeles Kings", "Golden State Warriros", "Huston Rocket" ], "answer": "Huston Rocket" } }, "maths": { "q1": {
    "question": "5 + 7 = ?", "options": [ "10", "11", "12", "13" ], "answer": "12" }, "q2": { "question": "12 - 8 = ?",
    "options": [ "1", "2", "3", "4" ], "answer": "4" } } } }
</json-viewer>

Load the JSON dynamically

<json-viewer id="json"></json-viewer>

<script>
    document.querySelector('#json').data = { prop1: true, prop2: 'test' };
</script>

Basic interactions

const viewer = document.querySelector('#json');

// Expand/collapse/filter
viewer.expand('**.name');
viewer.collapse(/name/);
viewer.filter('test.*.name');

// Search
const searchIterator = viewer.search('value');
// Scrolls to the node and highlight the value
searchIterator.next();

Custom renderer

This is an experimental feature and it may change in the future

The rendering of the values can be customized by defining a static method customRenderer in the custom element class. The function receives the value and the path of the node and it should return a HTML node or a Lit's TemplateResult object.

import { JsonViewer } from '@alenaksu/json-viewer/JsonViewer.js';

customElements.define(
    'json-viewer',
    class extends JsonViewer {
        static styles = [
            JsonViewer.styles,
            css`
                a {
                    color: white;
                    text-decoration: underline;
                }
            `
        ];

        static customRenderer(value, path) {
            if (typeof value === 'string') {
                if (URL.canParse(value)) {
                    return html`<a href="${value}" target="_blank">${value}</a>`;
                } else if (Date.parse(value)) {
                    return new Date(value).toLocaleString();
                }
            } else if (typeof value === 'number') {
                return value.toFixed(2);
            }

            return super.customRenderer(value);
        }
    }
);

Demo

The demo can also be run locally with

npm run start