Short description

The purpose of @gravity-ui/react-unipika is visualizing of JSON and YSON data objects. The library uses @gravity-ui/unipika and @gravity-ui/table internally.

Features

• virtualization
• two scroll modes: window scroll and container scroll
• collaps/expand objects/arrays
• search substring of key/value (case-sensitive and case-insensitive)
• render one literal per line
  • long strings are truncated by ellipsis
    • full value might be seen in dialog

Install

$ npm install @gravity-ui/react-unipika

Depending on your package manager you may need to install peerDependencies manually.

Usage

The library provides two entry points depending on your scrolling needs:

Window Scroll (default)

Use this when you want the component to scroll with the browser window:

import '@gravity-ui/uikit/styles/styles.scss';
import '@gravity-ui/unipika/styles/unipika.scss';

import {ReactUnipika} from '@gravity-ui/react-unipika/window-scroll';

function renderJson(data: any) {
  return <ReactUnipika value={data} />;
}

Container Scroll

Use this when you want the component to scroll within a specific container. You must provide a ref to the scroll container:

import '@gravity-ui/uikit/styles/styles.scss';
import '@gravity-ui/unipika/styles/unipika.scss';

import {ReactUnipika} from '@gravity-ui/react-unipika/container-scroll';

function renderJson(data: any) {
  const scrollContainerRef = React.useRef<HTMLDivElement>(null);

  return (
    <div ref={scrollContainerRef} style={{height: '500px', overflow: 'auto'}}>
      <ReactUnipika value={data} scrollContainerRef={scrollContainerRef} />
    </div>
  );
}

YSON notice

The library does not support YSON-format "as is", i.e. it is impossible to use/parse YSON data. But it provides the way to render JSON-objects as YSON, such JSON-objects has reserver field names like $attributes, $value.

See more examples in storybook.

Props

ReactUnipika Component Props

Prop	Type	Default	Description
value	any	required	The data to be rendered
settings	UnipikaSettings	See below	Settings for Unipika formatting
inline	boolean	false	Render in inline mode
children	React.ReactNode	-	React nodes to render as children
extraTools	React.ReactNode	-	Additional React nodes for tools
virtualized	boolean	true	Enable virtualization for better performance with large data
className	string	-	Custom CSS class name
customLayout	(args: {toolbar: React.ReactNode; content: React.ReactNode}) => React.ReactNode	-	Function to customize the layout
toolbarStickyTop	number	0	Top position in pixels for sticky toolbar
renderToolbar	(props: ToolbarProps) => React.ReactNode	-	Custom toolbar renderer function
collapseIconType	CollapseIconType	-	Type of collapse/expand icon to use
showContainerSize	boolean	-	Show the size of containers (objects/arrays)
initiallyCollapsed	boolean	-	Whether to render the tree initially collapsed
caseInsensitiveSearch	boolean	-	Enable case-insensitive search
renderError	(error: unknown) => React.ReactNode	-	Custom error renderer function
scrollContainerRef	React.RefObject<Element | null>	-	Required for container-scroll only. Reference to the scroll container element

UnipikaSettings

Setting	Type	Default	Description
asHTML	boolean	true	Render as HTML
format	string	'json'	Format type ('json', 'yson', 'raw-json')
compact	boolean	false	Use compact rendering
escapeWhitespace	boolean	true	Escape whitespace characters
showDecoded	boolean	true	Show decoded values
binaryAsHex	boolean	true	Display binary data as hexadecimal
nonBreakingIndent	boolean	-	Use non-breaking spaces for indentation
escapeYQLStrings	boolean	-	Escape YQL strings
decodeUTF8	boolean	-	Decode UTF-8 encoded strings
indent	number	-	Indentation size
break	boolean	-	Add line breaks
maxListSize	number	-	Maximum number of items to display in a list
maxStringSize	number	-	Maximum string length to display before truncating
omitStructNull	boolean	-	Omit null values in structures
treatValAsData	boolean	-	Treat values as data