# JsonViewer
Package: @mantine/code-highlight
Import: import { JsonViewer } from '@mantine/code-highlight';
Description: Interactive JSON data viewer with expand/collapse, type indicators and copy to clipboard

## Usage

`JsonViewer` is an interactive component for viewing JSON structures.

`JsonViewer` displays values the way `JSON.stringify` serializes them: values that implement `toJSON()` (for example, `Date`) are displayed as the result of `toJSON()`, and `Map` / `Set` are displayed as empty objects.

```tsx
import { JsonViewer } from '@mantine/code-highlight';
import { data } from './data';

function Demo() {
  return <JsonViewer value={data} />;
}
```


## Default expand depth

Use `defaultExpandDepth` prop to control how many levels are expanded by default. The root node is always expanded. With `1` (default), nested objects and arrays of the root node are collapsed:

```tsx
import { JsonViewer } from '@mantine/code-highlight';
import { data } from './data';

function Demo() {
  return <JsonViewer value={data} defaultExpandDepth={3} />;
}
```


`defaultExpandDepth` is applied only when the component mounts. If `value` is loaded later, change the `key` together with the data to apply it again, or control the expanded state with `expandedPaths` and `onExpandedPathsChange` props:

```tsx
import { JsonViewer } from '@mantine/code-highlight';

function Demo({ data }: { data: unknown }) {
  return <JsonViewer key={JSON.stringify(data)} value={data} defaultExpandDepth={2} />;
}
```

## Long arrays and objects

Use `maxDisplayLength` prop (`100` by default) to limit the number of entries displayed for a single object or array. The rest of the entries are replaced with a "... N more items" row.

Set `groupArraysAfterLength` prop to a number to split longer arrays into collapsible `[start...end]` groups instead. `maxDisplayLength` does not apply to grouped arrays.

## Root name

Use `rootName` prop to display a label for the root node. Set it to `false` (default) to hide it:

```tsx
import { JsonViewer } from '@mantine/code-highlight';
import { data } from './data';

function Demo() {
  return <JsonViewer value={data} rootName="response" />;
}
```


## Expand all / collapse all controls

Set `withControls` prop to display expand all and collapse all buttons. The controls are not displayed when `allExpanded` is set:

```tsx
import { JsonViewer } from '@mantine/code-highlight';
import { data } from './data';

function Demo() {
  return (
    <JsonViewer value={data} withControls />
  );
}
```


## Type badges and size

Set `withTypes` prop to display type badges next to values and `withSize` prop
to display the number of items in arrays and objects:

```tsx
import { JsonViewer } from '@mantine/code-highlight';
import { data } from './data';

function Demo() {
  return <JsonViewer value={data} withTypes withSize />;
}
```


## Copy button

Set `withCopy` prop to display a copy button when a row is hovered or focused:

```tsx
import { JsonViewer } from '@mantine/code-highlight';
import { data } from './data';

function Demo() {
  return <JsonViewer value={data} withCopy />;
}
```


## Collapse long strings

Use `collapseStringsAfterLength` prop to truncate long strings. Truncated strings
display a "show more" button that reveals the full value.

String values longer than 20 characters wrap onto multiple lines. These values have `data-wrap` attribute, use it to change the wrapping behavior with [Styles API](https://mantine.dev/llms/styles-styles-api.md).

```tsx
import { JsonViewer } from '@mantine/code-highlight';
import { data } from './data';

function Demo() {
  return <JsonViewer value={data} collapseStringsAfterLength={30} />;
}
```


## Sort keys

Set `sortKeys` prop to sort object keys alphabetically. You can also pass a custom
comparator function:

```tsx
import { JsonViewer } from '@mantine/code-highlight';
import { data } from './data';

function Demo() {
  return <JsonViewer value={data} sortKeys />;
}
```


## Highlight items

Use `highlightItems` prop to highlight properties with diff-style colors. It is an object:
keys are property paths created with `serializeJsonViewerPath` function, values are `added` or `removed`:

```tsx
import {
  JsonViewer,
  JsonViewerHighlightType,
  serializeJsonViewerPath,
} from '@mantine/code-highlight';
import { data } from './data';

const highlightItems: Record<string, JsonViewerHighlightType> = {
  [serializeJsonViewerPath(['version'])]: 'added',
  [serializeJsonViewerPath(['deprecated'])]: 'removed',
  [serializeJsonViewerPath(['author', 'url'])]: 'added',
};

function Demo() {
  return (
    <JsonViewer
      value={data}
      highlightItems={highlightItems}
      defaultExpandDepth={3}
    />
  );
}
```


## All expanded

Set `allExpanded` prop to expand all nodes and disable collapse interactions:

```tsx
import { JsonViewer } from '@mantine/code-highlight';
import { data } from './data';

function Demo() {
  return <JsonViewer value={data} allExpanded />;
}
```


## Line numbers

Set `withLineNumbers` prop to display line numbers alongside the JSON content:

```tsx
import { JsonViewer } from '@mantine/code-highlight';
import { data } from './data';

function Demo() {
  return <JsonViewer value={data} withLineNumbers />;
}
```


## Chevrons

Set `withChevrons` prop to display expand/collapse chevrons next to collapsible nodes:

```tsx
import { JsonViewer } from '@mantine/code-highlight';
import { data } from './data';

function Demo() {
  return <JsonViewer value={data} withChevrons />;
}
```


## Keyboard navigation

`JsonViewer` supports keyboard navigation similar to the [Tree](https://mantine.dev/llms/core-tree.md) component:

* `↑` / `↓` – move focus between visible nodes
* `→` – expand a collapsed node, or move focus to its first child
* `←` – collapse an expanded node, or move focus to its parent
* `Enter` / `Space` – toggle expand/collapse on collapsible nodes, trigger `onValueSelect` on primitive nodes
* `Ctrl + C` / `⌘ + C` – copy the focused node value when `withCopy` prop is set

## Accessibility

`JsonViewer` renders its content as an ARIA tree. `rootName` prop is used as the accessible name of the tree, when it is not set, the tree is labelled `JSON`.

The component is always rendered left-to-right, regardless of the [direction](https://mantine.dev/llms/styles-rtl.md) of the application.


#### Props

**JsonViewer props**

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| allExpanded | boolean | - | When true, all nodes are expanded and expand/collapse is disabled |
| collapseAllLabel | string | - | Label for collapse all button |
| collapseStringsAfterLength | number \| false | - | Collapse strings longer than this value |
| copiedLabel | string | - | Label for copied state |
| copyLabel | string | - | Label for copy button |
| defaultExpandDepth | number | - | Number of levels to expand by default. Applied only to the `value` present on mount; pass a `key` or use controlled `expandedPaths` to re-apply it after `value` changes. |
| expandAllLabel | string | - | Label for expand all button |
| expandedPaths | string[] | - | Controlled expanded paths |
| fontSize | MantineSize \| number | - | Font size |
| groupArraysAfterLength | number \| false | - | Group arrays into chunks when array length exceeds this value |
| highlightItems | Record<string, JsonViewerHighlightType> | - | Map of JSON paths to highlight type ('added' or 'removed'), use serializeJsonViewerPath to build keys |
| indentWidth | number | - | Indent width in px |
| maxDisplayLength | number | - | Max number of items to show before truncation |
| onExpandedPathsChange | (paths: string[]) => void | - | Called when expanded paths change |
| onValueSelect | (path: string[], value: any) => void | - | Called when a value is selected/clicked |
| radius | MantineRadius \| number | - | Key of `theme.radius` or any valid CSS value to set border-radius |
| rootName | string \| false | - | Label displayed for the root node |
| sortKeys | boolean \| ((a: string, b: string) => number) | - | Sort object keys |
| value | any | required | JSON data to display |
| withBorder | boolean | - | Adds border to the root element |
| withChevrons | boolean | - | Whether to show expand/collapse chevrons |
| withControls | boolean | - | Whether to show expand all / collapse all controls |
| withCopy | boolean | - | Whether to show copy button on hover for individual nodes |
| withCopyButton | boolean | - | Whether to show a copy button to copy the entire JSON |
| withKeyQuotes | boolean | - | Whether to show quotes around keys |
| withLineNumbers | boolean | - | Whether to show line numbers |
| withQuotes | boolean | - | Whether to show quotes around string values |
| withSize | boolean | - | Whether to show item count for objects/arrays |
| withTypes | boolean | - | Whether to show type badges next to values |


#### Styles API

JsonViewer component supports Styles API. With Styles API, you can customize styles of any inner element. Follow the documentation to learn how to use CSS modules, CSS variables and inline styles to get full control over component styles.

**JsonViewer selectors**

| Selector | Static selector | Description |
|----------|----------------|-------------|
| root | .mantine-JsonViewer-root | Root element |
| node | .mantine-JsonViewer-node | Container for a single tree node |
| toggle | .mantine-JsonViewer-toggle | Expand/collapse chevron icon |
| key | .mantine-JsonViewer-key | Object key label |
| value | .mantine-JsonViewer-value | Primitive value display |
| bracket | .mantine-JsonViewer-bracket | Opening/closing brackets |
| type | .mantine-JsonViewer-type | Type badge |
| size | .mantine-JsonViewer-size | Item/key count label |
| ellipsis | .mantine-JsonViewer-ellipsis | Collapsed content indicator or show more/less button |
| copyButton | .mantine-JsonViewer-copyButton | Copy to clipboard button |
| content | .mantine-JsonViewer-content | Content wrapper with padding |
| row | .mantine-JsonViewer-row | Single row wrapper for a node |
| scrollarea | .mantine-JsonViewer-scrollarea | Scroll area wrapper |
| lineNumbers | .mantine-JsonViewer-lineNumbers | Line numbers column |
| wrapper | .mantine-JsonViewer-wrapper | Flex wrapper around line numbers and content |
| copyAllButton | .mantine-JsonViewer-copyAllButton | Copy all JSON button positioned at top-right corner |
| controls | .mantine-JsonViewer-controls | Expand all / collapse all controls container |
| control | .mantine-JsonViewer-control | Expand all / collapse all button |

**JsonViewer CSS variables**

| Selector | Variable | Description |
|----------|----------|-------------|
| root | --jv-radius | Border radius |
| root | --jv-fz | Font size |
| root | --jv-indent | Indent width per nesting level |

**JsonViewer data attributes**

| Selector | Attribute | Condition | Value |
|----------|-----------|-----------|-------|
| root | data-with-border | `withBorder` prop is set | - |
| node | data-type | - | `array`, `object` or primitive value type name |
| node | data-highlight | Node path is present in `highlightItems` | `added` or `removed` |
| row | data-root | Root node row | - |
| row | data-hoverable | Row can be expanded, collapsed or selected | - |
| toggle | data-expanded | Node is expanded | - |