[![GitHub release](https://img.shields.io/github/v/release/alenaksu/json-viewer.svg)](https://github.com/alenaksu/json-viewer/releases) [![npm](https://badgen.net/npm/v/@alenaksu/json-viewer)](https://www.npmjs.com/package/@alenaksu/json-viewer) [![downloads](https://badgen.net/npm/dt/@alenaksu/json-viewer)](https://www.npmjs.com/package/@alenaksu/json-viewer) [![Known Vulnerabilities](https://snyk.io/test/npm/@alenaksu/json-viewer/badge.svg)](https://snyk.io/test/npm/@alenaksu/json-viewer) [![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/alenaksu/json-viewer/master/LICENSE) [![Published on webcomponents.org](https://img.shields.io/badge/webcomponents.org-published-blue.svg)](https://www.webcomponents.org/element/@alenaksu/json-viewer) A Web Component to visualize JSON data in a tree view --- - [Installation](#installation) - [From CDN](#from-cdn) - [From NPM](#from-npm) - [Usage](#usage) - [Attributes](#attributes) - [Properties](#properties) - [Methods](#methods) - [CSS Parts](#css-parts) - [CSS custom properties](#css-custom-properties) - [Basic Usage](#basic-usage) - [Load the JSON dynamically](#load-the-json-dynamically) - [Basic interactions](#basic-interactions) - [Custom renderer](#custom-renderer) - [Demo](#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. ```html ``` ### From NPM Install the component through NPM: ```sh 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`. ```js 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: ```js import { JsonViewer } '@alenaksu/json-viewer/JsonViewer.js'; class MyJsonViewer extends JsonViewer { ... } customElements.define('my-json-viewer', MyJsonViewer); ``` --- ## Usage ```html ``` ### 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 ```css 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 ```html { "quiz": { "sport": { "q1": { "question": "Which one is correct team name in NBA?", "options": [ "New York Bulls", "Los Angeles Kings", "Golden State Warriros", "Houston Rockets" ], "answer": "Houston Rockets" } }, "maths": { "q1": { "question": "5 + 7 = ?", "options": [ "10", "11", "12", "13" ], "answer": "12" }, "q2": { "question": "12 - 8 = ?", "options": [ "1", "2", "3", "4" ], "answer": "4" } } } } ``` ### Load the JSON dynamically ```html ``` ### Basic interactions ```js 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. ```js 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`${value}`; } 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 ```sh npm run start ```