@gfazioli/mantine-json-tree

Upgrading from an older major version? See the Upgrade guide for breaking changes and step-by-step migration instructions.

What's new

• Structural editing — rename keys, add and remove keys and items, reorder arrays (structuralEdits)
• Entry limit — long objects and arrays end with a "… N more" row that reveals the next page (maxDisplayLength)
• Locked expansion — every node open, none can be collapsed (allExpanded)
• Quote style — show or hide the quotes around strings and keys (withQuotes, withKeyQuotes)
• Labels — translate every built-in string, and every icon button now has an accessible name (labels)
• Indentation width (indentWidth) and a root without a label (rootName={false})
• Diff highlighting — mark nodes as added, removed or changed (highlightNode)
• Large arrays split into collapsible [start…end] groups (groupArraysAfterLength)
• Long strings cut with a "show more" toggle (collapseStringsAfterLength)
• Type badges next to every value (showValueTypes)
• Sorted keys, alphabetical or with your own comparator (sortKeys)
• Editable values — click a string, number or boolean to edit it in place (editable, onChange)
• Circular references are detected and marked instead of crashing the component
• Search with text highlight, auto-expand, and filtered tree view (withSearch)
• Redesigned toolbar with key count badge, global copy, search toggle, and modern icons
• Paper wrapper with withBorder for bordered container look
• Root name customization (rootName prop)
• Global copy button to copy entire JSON to clipboard (withCopyAll)
• Key count badge showing total keys/items next to title (withKeyCountBadge)
• Dark mode support with automatic color adaptation
• Line numbers display (showLineNumbers)
• Path tooltip on hover (showPathOnHover)
• Max height with scrollable container (maxHeight)
• Controlled expand/collapse state (expanded, onExpandedChange)
• onExpand and onCollapse callbacks for individual node toggling
• Keyboard copy: Ctrl+C / Cmd+C copies the focused node when withCopyToClipboard is enabled
• Responsive size prop via Mantine breakpoint objects (CSS-native, no re-renders)

Installation

yarn add @gfazioli/mantine-json-tree

After installation import package styles at the root of your application:

import '@gfazioli/mantine-json-tree/styles.css';

You can import styles within a layer @layer mantine-json-tree by importing @gfazioli/mantine-json-tree/styles.layer.css file.

import '@gfazioli/mantine-json-tree/styles.layer.css';

Comparison with Mantine JsonViewer

Since version 9.7, Mantine ships a first-party JsonViewer in @mantine/code-highlight. The basics overlap — collapsible nodes, copy to clipboard, type badges, diff highlighting, keyboard navigation — but the two make different trade-offs.

When to use which. Reach for JsonViewer for a light, read-only view of JSON that came over the wire, especially if you already use @mantine/code-highlight. Reach for JsonTree when the data is a live JavaScript value — Dates, Maps, Sets, functions, circular graphs — when you need to search it, or to edit it in place, values and structure alike, or when the tree is a tool of its own, with a title, a sticky toolbar and indent guides.

Usage

The JsonTree is interactive JSON tree viewer component built with Mantine's Tree component. Features collapsible nodes, syntax highlighting with type-specific colors, copy-to-clipboard functionality, item count badges, configurable expansion depth, and smooth animations. Perfect for debugging API responses, exploring complex data structures, and developer tools.

import { JsonTree } from "@gfazioli/mantine-json-tree";
import { data } from './data';

function Demo() {
  return <JsonTree title="My JSON" size="sm" withBorder withKeyCountBadge withExpandAll withCopyAll withSearch withCopyToClipboard showIndentGuides showItemsCount showLineNumbers showPathOnHover data={data} maxDepth={1} defaultExpanded/>;
}

Editing Values

Set editable to let a reader change a value in place. Click a string or a number to open an inline editor — Enter commits, Escape cancels, moving focus commits — or click a boolean to toggle it outright, since it has exactly one other state. With a row focused, Enter opens its editor too, so the whole flow works from the keyboard without adding a tab stop per value.

JsonTree is controlled while editing: it never keeps its own copy of your data. onChange hands you the next value, and it only takes effect once you feed it back through data.

data is typed unknown, so onChange hands the next value back as unknown too. Editing a value never changes the shape of the object — a string stays a string, a number a number — so casting it back to your own type is safe:

const [data, setData] = useState<Profile>(initial);

<JsonTree data={data} editable onChange={(next) => setData(next as Profile)} />

The original object is never mutated. Only the spine down to the edited node is rebuilt, so every Date, Map, Set, RegExp, BigInt, function and React element elsewhere in the tree keeps its identity — a structuredClone or a JSON round-trip would flatten or destroy all of them.

import { useState } from 'react';
import { JsonTree, JsonTreeChange } from "@gfazioli/mantine-json-tree";
import { Paper, Stack, Text } from '@mantine/core';

interface Profile {
  name: string;
  age: number;
  isAdmin: boolean;
  createdAt: Date;
  address: { city: string; zip: string };
  tags: string[];
}

function Demo() {
  const [data, setData] = useState<Profile>({
    name: 'Jamie Chen',
    age: 34,
    isAdmin: false,
    createdAt: new Date('2024-01-15T10:30:00Z'),
    address: {
      city: 'Anytown',
      zip: '12345',
    },
    tags: ['react', 'mantine'],
  });

  const [lastChange, setLastChange] = useState<JsonTreeChange | null>(null);

  return (
    <Stack>
      <Paper withBorder>
        <JsonTree
          data={data}
          title="profile.json"
          defaultExpanded
          maxDepth={-1}
          editable
          onChange={(next, change) => {
            // editing a value never changes the shape, so the cast is safe
            setData(next as Profile);
            setLastChange(change);
          }}
          // zip stays read-only even though its type is editable
          isEditable={({ key }) => key !== 'zip'}
          validate={({ type, value }) =>
            type === 'string' && String(value).trim() === '' ? 'Cannot be empty' : null
          }
        />
      </Paper>

      <Text size="sm" c="dimmed">
        {lastChange
          ? `${lastChange.path}: ${JSON.stringify(lastChange.previousValue)} → ${JSON.stringify(lastChange.value)}`
          : 'Click a value to edit it. Enter commits, Escape cancels.'}
      </Text>
    </Stack>
  );
}

What can be edited

editableTypes defaults to ['string', 'number', 'boolean']; anything outside it stays read-only. Two kinds of node can never be edited, whatever you put in that list:

• Map and Set entries. They are displayed under a synthetic key — a Map key can be any value at all, including an object — so there is no address to write back to.
• Function properties expanded with displayFunctions="as-object". Those properties belong to a synthetic object that does not exist in your data.

isEditable gates individual nodes, and validate rejects a value by returning a message:

<JsonTree
  data={data}
  editable
  onChange={setData}
  isEditable={({ path }) => path !== 'root.id'}
  validate={({ value }) => (String(value).trim() === '' ? 'Cannot be empty' : null)}
/>

Addressing a node

onChange receives a change object carrying both ways of naming the node:

• path — the display label, e.g. root.address.city. It is not unique: { 'a.b': 1 } and { a: { b: 1 } } both produce root.a.b, and an array index reads the same as a numeric object key.
• pathSegments — the real address, one step per level, with object keys as strings and array indices as numbers. This is what the write is performed against, so an edit always lands on the node you clicked.

Use path for display and logging; use pathSegments whenever you need to act on the node.

Editing Structure

Add structuralEdits to editable and the reader can change the shape of the data too: rename an object key, add a key or an item, remove one, and move the items of an array. Pass true for all four, or a list such as ['add', 'remove'] for some of them.

• Rename: click a key, or press F2 on its row, and type the new name. A key the object already has is refused, and validateKey can refuse others.
• Add: the + button on an object asks for the new key; on an array it appends an item. A new entry starts with the type of the container's last entry, emptied ('', 0, false, null, {}, []), or with whatever getNewValue returns; a new string or number opens its editor at once.
• Remove: the bin button, or Delete / Backspace on the focused row.
• Reorder: the arrow buttons on an array item, or Alt + ↑ / ↓.

import { useState } from 'react';
import { JsonTree, type JsonTreeChange } from '@gfazioli/mantine-json-tree';
import { Paper, Stack, Text } from '@mantine/core';

function Demo() {
  const [data, setData] = useState<unknown>({
    name: 'release-checklist',
    owner: 'Jamie Chen',
    steps: ['bump version', 'build', 'publish', 'announce'],
    settings: { dryRun: false, retries: 3 },
  });
  const [lastChange, setLastChange] = useState<JsonTreeChange | null>(null);

  return (
    <Stack>
      <Paper withBorder>
        <JsonTree
          data={data}
          title="checklist.json"
          defaultExpanded
          maxDepth={-1}
          editable
          structuralEdits
          onChange={(next, change) => {
            setData(next);
            setLastChange(change);
          }}
          validateKey={(key) => (key.trim() === '' ? 'A key cannot be empty' : null)}
        />
      </Paper>

      <Text size="sm" c="dimmed">
        {lastChange
          ? `${lastChange.action} · ${lastChange.previousPath ? `${lastChange.previousPath} → ` : ''}${lastChange.path}`
          : 'Hover a row: + adds, the arrows move an item, the bin removes. Click a key to rename it.'}
      </Text>
    </Stack>
  );
}

onChange reports each change with an action — 'edit' for a value, or 'rename', 'add', 'remove' and 'reorder' — and a rename or a reorder also carries previousPath, previousPathSegments and previousKey. Every write goes through pathSegments, so it lands on the node you meant even when two keys share a display path, and, as with values, only the spine down to the change is rebuilt.

Keys and indices are part of every path below them, so a rename or a shifted index changes the path of a whole subtree. JsonTree carries its own state across: expanded nodes stay expanded under their new paths (a controlled expanded gets the new list through onExpandedChange), revealed pages stay revealed, and focus follows the change — to the renamed row, the moved item, or the entry that took a removed one's place. The same entries as for values stay read-only: Map and Set entries, the [start…end] groups, reference cycles, and whatever isEditable refuses.

Search

Enable withSearch to add a search toggle in the toolbar. When active, the tree filters to show only branches with matching keys or values. Direct matches get an amber background highlight, and the matching text portion is highlighted inline. Parent nodes are preserved for context. Clearing the search restores the previous expand state.

import { JsonTree } from '@gfazioli/mantine-json-tree';

function Demo() {
  return (
    <JsonTree
      data={data}
      title="API Response"
      rootName="root"
      withBorder
      withSearch
      withExpandAll
      withKeyCountBadge
      withCopyAll
      defaultExpanded
    />
  );
}

Customizing the search input

Use searchInputProps to forward any prop to the internal TextInput — classNames, styles, vars, variant, radius, size, leftSection, and so on. Because Mantine applies styles inline, this works without specificity hacks or !important.

import { JsonTree } from '@gfazioli/mantine-json-tree';

function Demo() {
  return (
    <JsonTree
      data={data}
      title="Custom search input"
      withBorder
      withSearch
      defaultExpanded
      searchInputProps={{
        radius: 'xl',
        variant: 'filled',
        placeholder: 'Look up keys or values…',
        styles: {
          input: {
            backgroundColor: 'var(--mantine-color-dark-7)',
            borderColor: 'var(--mantine-color-dark-4)',
            color: 'var(--mantine-color-gray-0)',
          },
        },
      }}
    />
  );
}

Copy to Clipboard

Both per-node and global copy buttons provide visual feedback — the icon briefly changes to a green checkmark after a successful copy.

The global copy button (withCopyAll) copies the raw JSON data without the rootName wrapper. The rootName is a display-only label and is not included in the copied output. This makes the copied JSON directly usable in code and API tools.

What lands on the clipboard is what the tree shows. JSON.stringify alone cannot express everything the tree renders — it returns undefined for functions, symbols and undefined, and throws on BigInt and on any value holding a reference cycle — so those fall back to the rendered form rather than copying the literal text undefined or silently doing nothing.

Root Name

Use the rootName prop to customize the label of the root node. Defaults to "root". This is useful for API responses, config files, or when displaying multiple trees with different root labels. Note that rootName is display-only — it does not affect the copied JSON output. Pass rootName={false} to show the root without a label; paths keep their root prefix, so expanded, onNodeClick and the path tooltip are the same either way:

import { JsonTree } from '@gfazioli/mantine-json-tree';
import { Stack } from '@mantine/core';

function Demo() {
  return (
    <Stack>
      <JsonTree
        data={{ id: 1, name: 'Alice', role: 'admin' }}
        rootName="response"
        title="Custom Root Name"
        withBorder
        withKeyCountBadge
        defaultExpanded
      />
      <JsonTree
        data={[1, 2, 3]}
        rootName="items"
        title="Array Root Name"
        withBorder
        withKeyCountBadge
        defaultExpanded
      />
      <JsonTree
        data={{ id: 1, name: 'Alice', role: 'admin' }}
        rootName={false}
        title="No Root Label"
        withBorder
        defaultExpanded
      />
    </Stack>
  );
}

Syntax Highlighting values

Below is an example of syntax highlighting for different JSON value types: strings, numbers, booleans, nulls, objects, and arrays. Each type is displayed in a distinct color for better readability.

import { JsonTree } from "@gfazioli/mantine-json-tree";
import { Paper, Stack } from '@mantine/core';

function Demo() {
  return (
    <Stack>
      <Paper withBorder>
        <JsonTree data="Hello, World!" defaultExpanded title="Simple string" />
      </Paper>
      <Paper withBorder>
        <JsonTree data={42} defaultExpanded title="Number value" />
      </Paper>
      <Paper withBorder>
        <JsonTree data={true} defaultExpanded title="Boolean value (true)" />
      </Paper>
      <Paper withBorder>
        <JsonTree data={false} defaultExpanded title="Boolean value (false)" />
      </Paper>
      <Paper withBorder>
        <JsonTree data={null} defaultExpanded title="Null value" />
      </Paper>
      <Paper withBorder>
        <JsonTree data={{ key1: 'value1', key2: 123, key3: false, key4: null }} defaultExpanded title="Object value" />
      </Paper>
      <Paper withBorder>
        <JsonTree data={['string', 456, true, null, { nestedKey: 'nestedValue' }]} defaultExpanded title="Array value" />
      </Paper>
    </Stack>
  );
}

Quote Style

Strings are shown between quotes and object keys without them, as Mantine's JsonViewer does by default. withQuotes={false} drops the quotes around strings, and withKeyQuotes adds them around object keys — never around an array index, a Map or Set entry or a group label, which JSON would not quote either. Search matches the text as it is displayed, and copying still produces valid JSON.

import { JsonTree } from '@gfazioli/mantine-json-tree';
import { SimpleGrid } from '@mantine/core';

const data = { name: 'Ada', languages: ['en', 'fr'], address: { city: 'London' } };

function Demo() {
  return (
    <SimpleGrid cols={{ base: 1, sm: 2 }}>
      <JsonTree data={data} title="JSON style" withBorder defaultExpanded maxDepth={-1} withKeyQuotes />
      <JsonTree data={data} title="No quotes" withBorder defaultExpanded maxDepth={-1} withQuotes={false} />
    </SimpleGrid>
  );
}

Special Value Types

JsonTree supports modern JavaScript types beyond standard JSON primitives. These include Date objects, special numeric values (NaN, Infinity), BigInt for large integers, Symbols, RegExp patterns, and ES6 collections like Map and Set. Each type is displayed with distinct syntax highlighting and formatting:

• Date: Displayed in ISO 8601 format (e.g., 2024-01-15T10:30:00.000Z)
• NaN / Infinity: Special numeric values shown with their standard JavaScript representation
• BigInt: Large integers displayed with the n suffix (e.g., 9007199254740991n)
• Symbol: Unique identifiers shown with their description (e.g., Symbol(unique))
• RegExp: Regular expressions displayed with their pattern and flags (e.g., /pattern/gi)
• Map: Key-value collections that are expandable to show their entries
• Set: Unique value collections that are expandable to show their elements
• React Elements: React components displayed with their component name (e.g., <Loader />)

React elements are recognised by their internal $$typeof marker, so ordinary data is never mistaken for one. An object such as { type: 'text', props: { label: 'Name' } } — a common shape in form-builder and low-code JSON — is rendered as a regular, expandable object.

All colors can be customized using CSS variables for each type.

import { JsonTree } from "@gfazioli/mantine-json-tree";
import { Loader, Paper } from '@mantine/core';

function Demo() {
  const specialTypes = {
    // React components
    reactLoader: <Loader size="xs" />,
    reactButton: <button type="button">Click me</button>,
    htmlDiv: <div>Hello World</div>,
    // Date objects - displayed in ISO format
    createdAt: new Date('2024-01-15T10:30:00Z'),
    lastModified: new Date('2024-06-20T14:45:30Z'),

    // Special numeric values
    notANumber: NaN,
    positiveInfinity: Infinity,
    negativeInfinity: -Infinity,

    // BigInt for large integers
    bigInteger: BigInt('9007199254740991'),
    userId: BigInt(123456789),

    // Symbols for unique identifiers
    globalSymbol: Symbol.for('app.config'),
    registryKey: Symbol.for('app.registry'),

    // Regular expressions
    emailPattern: /^[\w-.]+@([\w-]+\.)+[\w-]{2,4}$/g,
    phonePattern: new RegExp('\\d{3}-\\d{3}-\\d{4}'),

    // Map collections (key-value pairs)
    userMap: new Map([
      ['user1', { name: 'Alice', role: 'admin' }],
      ['user2', { name: 'Bob', role: 'user' }],
      [123, 'numeric key example'],
    ]),

    // Set collections (unique values)
    tags: new Set(['javascript', 'typescript', 'react']),
    uniqueNumbers: new Set([1, 2, 3, 4, 5]),

    // Nested combinations
    metadata: {
      timestamp: new Date('2024-12-25T00:00:00Z'),
      categories: new Set(['frontend', 'backend']),
      config: new Map([
        ['version', '1.0.0'],
        ['environment', 'production'],
      ]),
    },
  };

  return (
    <Paper withBorder>
      <JsonTree
        data={specialTypes}
        title="special-types.json"
        defaultExpanded
        withExpandAll
        showItemsCount
      />
    </Paper>
  );
}

Circular References

Object graphs that point back at themselves are everywhere in real debugging sessions — a child holding a reference to its parent, a linked list, a cached entity pointing at the store that owns it. JsonTree walks the current branch and stops as soon as a value reappears on its own ancestor chain, rendering it as [Circular] rather than recursing until the stack overflows.

Only the ancestor chain is tracked, never every value already visited. A value referenced from two different branches is shared, not circular, so it keeps expanding normally in both places — as the config object does below.

import { JsonTree } from "@gfazioli/mantine-json-tree";
import { Paper } from '@mantine/core';

function Demo() {
  // A node graph: every child points back at its parent, and a shared
  // "config" object is referenced from two different branches.
  const config = { theme: 'dark', locale: 'en' };

  const root: any = {
    id: 'root',
    config,
    child: {
      id: 'child',
      config,
    },
  };

  root.self = root;
  root.child.parent = root;

  return (
    <Paper withBorder>
      <JsonTree
        data={root}
        title="graph.json"
        defaultExpanded
        maxDepth={-1}
        withExpandAll
        showItemsCount
      />
    </Paper>
  );
}

Diff Highlighting

highlightNode is called for every node except the synthetic [start…end] groups of groupArraysAfterLength, and returns how it changed: 'added', 'removed', 'changed', or null to leave it as is. It receives the node's path, pathSegments, key, type and value, so a diff can be computed against any previous version of the data — below, by reading the same pathSegments in both versions.

The colors come from the --json-tree-highlight-added-color, --json-tree-highlight-removed-color and --json-tree-highlight-changed-color variables, and each highlighted row carries a data-json-tree-highlight attribute for your own styles.

import {
  JsonTree,
  type JsonTreeHighlight,
  type JsonTreeHighlightPayload,
} from '@gfazioli/mantine-json-tree';

const before = {
  name: 'Alice',
  age: 30,
  role: 'editor',
  tags: ['admin'],
  address: { city: 'Rome', zip: '00100' },
};

const after = {
  name: 'Alice',
  age: 31,
  tags: ['admin', 'billing'],
  address: { city: 'Milan', zip: '00100' },
  email: 'alice@example.com',
};

/** Read a value by its path segments, telling "missing" apart from "undefined" */
function getAt(value: unknown, segments: readonly (string | number)[]) {
  let current: any = value;
  for (const segment of segments) {
    if (current === null || typeof current !== 'object' || !(segment in current)) {
      return { found: false, value: undefined };
    }
    current = current[segment];
  }
  return { found: true, value: current };
}

function highlightNode({ pathSegments }: JsonTreeHighlightPayload): JsonTreeHighlight | null {
  if (!pathSegments || pathSegments.length === 0) {
    return null;
  }
  const previous = getAt(before, pathSegments);
  const next = getAt(after, pathSegments);
  if (!previous.found) {
    return 'added';
  }
  if (!next.found) {
    return 'removed';
  }
  return JSON.stringify(previous.value) === JSON.stringify(next.value) ? null : 'changed';
}

function Demo() {
  // Show the removed keys too: everything from "before", overwritten by "after"
  const merged = { ...before, ...after };

  return (
    <JsonTree
      data={merged}
      title="user.json"
      defaultExpanded
      maxDepth={-1}
      withBorder
      highlightNode={highlightNode}
    />
  );
}

Large Data

Three props keep big payloads readable:

• groupArraysAfterLength splits an array longer than the given length into collapsible [start…end] groups of that many items, so a large array does not render every item at once. Each group is one more level of the tree (and of maxDepth); the items inside keep their own paths, so search, copy and editing work as before.
• collapseStringsAfterLength cuts longer strings and adds a "show more" toggle. While a search is active the whole string is shown, so a match past the cut stays visible.
• showValueTypes adds a type badge next to every value: string, int, float, bool, null, object, array, date and so on.

import { JsonTree } from '@gfazioli/mantine-json-tree';

const data = {
  description:
    'A long description that would push every other value off the screen if it were shown in full on a single line.',
  scores: Array.from({ length: 250 }, (_, index) => Math.round(Math.sin(index) * 1000) / 10),
  owner: { name: 'Alice', verified: true, deletedAt: null },
};

function Demo() {
  return (
    <JsonTree
      data={data}
      title="report.json"
      defaultExpanded
      maxDepth={1}
      withBorder
      showItemsCount
      showValueTypes
      collapseStringsAfterLength={40}
      groupArraysAfterLength={100}
    />
  );
}

Entry limit

maxDisplayLength shows at most that many entries of an object, array, Map or Set, and closes it with a "… N more items" row. That row is a button: a click, or Enter on the focused row, reveals the next as many entries and moves focus to the first of them. An array split by groupArraysAfterLength is left whole, and the limit is off while a search is active, so no match hides behind it. Copy, search, expand all and the key count badge always work on the full value.

import { JsonTree } from '@gfazioli/mantine-json-tree';

const data = {
  users: Array.from({ length: 1000 }, (_, index) => ({ id: index + 1, name: `user-${index + 1}` })),
  flags: Object.fromEntries(Array.from({ length: 40 }, (_, index) => [`flag${index + 1}`, index % 3 === 0])),
};

function Demo() {
  return (
    <JsonTree
      data={data}
      title="dump.json"
      defaultExpanded
      maxDepth={2}
      withBorder
      withSearch
      withKeyCountBadge
      maxDisplayLength={10}
    />
  );
}

Sort Keys

Set sortKeys to show object keys in alphabetical order, or pass a comparator such as (a, b) => b.localeCompare(a). Arrays keep their order, and so does the data: sorting only changes what is displayed, so paths and edits are unaffected. Memoize a comparator, since a new function on every render rebuilds the tree.

Indent Guides

Display vertical lines to visualize nesting levels, similar to Visual Studio Code. The guides use 5 distinct colors that cycle for deeper nesting levels. indentWidth sets how far each level is indented, in px (32 by default), and the guides follow it.

import { JsonTree } from "@gfazioli/mantine-json-tree";
import { data } from './data';

function Demo() {
  return (
    <JsonTree 
      data={data} 
      defaultExpanded 
      maxDepth={-1}
      showIndentGuides
      title="JSON with Indent Guides"
    />
  );
}

Line Numbers

Display line numbers alongside each node, similar to code editors. This is useful for referencing specific parts of the JSON structure.

import { JsonTree } from "@gfazioli/mantine-json-tree";
import { data } from './data';

function Demo() {
  return (
    <JsonTree
      data={data}
      defaultExpanded
      maxDepth={-1}
      showLineNumbers
      title="JSON with Line Numbers"
    />
  );
}

Sticky Header

You may enable sticky headers for better context when scrolling through large JSON structures. When enabled, the header of each expanded node remains visible at the top of the scrollable area as you navigate through its child elements. You can also set an offset to accommodate fixed headers in your layout.

import { JsonTree } from "@gfazioli/mantine-json-tree";
import { data } from './data';

function Demo() {
  return (
    <JsonTree stickyHeader
      data={data}
      title="data.json"
      defaultExpanded
      withExpandAll
      maxHeight={300}
      styles={{
        header: { backgroundColor: 'var(--mantine-color-default)' },
      }}
    />
  );
}

Icons

You can customize the expand/collapse icons used in the JsonTree component by providing your own icons via the expandControlIcon and collapseControlIcon props. The default icons are simple chevrons, but you can replace them with any React component or icon of your choice.

Note: If only the expandControlIcon is provided, the component will automatically use it for both expand and collapse states, by rotating (90deg) it accordingly. If only the collapseControlIcon is provided, the default expand icon will be used. Of course, you can provide both icons for complete customization.

import { JsonTree } from "@gfazioli/mantine-json-tree";
import { Paper, SimpleGrid, Text, Title } from '@mantine/core';
import { data } from './data';

function Demo() {
  return (
    <SimpleGrid cols={3}>
      <Paper withBorder p="md">
        <Title order={4}>Only Expand Icons</Title>
        <JsonTree
          title="demo.json"
          showIndentGuides
          data={data}
          expandControlIcon={<span>👉</span>}
        />
      </Paper>
      <Paper withBorder p="md">
        <Title order={4}>Only Collapse Icons</Title>
        <JsonTree
          title="demo.json"
          showIndentGuides
          data={data}
          collapseControlIcon={<span>👇</span>}
        />
      </Paper>
      <Paper withBorder p="md">
        <Title order={4}>Both Expand and Collapse Icons</Title>
        <JsonTree
          title="demo.json"
          showIndentGuides
          data={data}
          expandControlIcon={
            <Text fz={24} c="red">
              ⊕
            </Text>
          }
          collapseControlIcon={<Text fz={24}>⊖</Text>}
        />
      </Paper>
    </SimpleGrid>
  );
}

Function Display

By default, functions in JSON data are displayed as strings (e.g., [Function: name]). You can control how functions are handled using the displayFunctions prop:

• as-string (default): Display functions as formatted strings showing their name
• hide: Completely omit functions from the tree
• as-object: Treat functions as objects and display their properties

import { JsonTree } from '@gfazioli/mantine-json-tree';
import { Code, Paper, Stack } from '@mantine/core';

const dataWithFunctions = {
  name: 'UserProfile',
  age: 25,
  onClick: function handleClick() {
    console.log('clicked');
  },
  calculate: (a: number, b: number) => a + b,
  methods: {
    async fetchData() {
      return 'data';
    },
    process: function process(value: string) {
      return value.toUpperCase();
    },
  },
  data: [1, 2, 3],
  isActive: true,
};

function Demo() {
  return (
    <Stack>
      <Paper withBorder p="sm">
        <Code>as-string</Code>
        <JsonTree data={dataWithFunctions} defaultExpanded displayFunctions="as-string" mb="md" />
      </Paper>
      <Paper withBorder p="sm">
        <Code>hide</Code>
        <JsonTree data={dataWithFunctions} defaultExpanded displayFunctions="hide" mb="md" />
      </Paper>
      <Paper withBorder p="sm">
        <Code>as-object</Code>
        <JsonTree data={dataWithFunctions} defaultExpanded displayFunctions="as-object" />
      </Paper>
    </Stack>
  );
}

Callbacks

Use the onNodeClick callback to handle clicks on any node in the tree, and the onCopy callback to react when a value is copied to clipboard. Both callbacks provide the relevant data for integration with your application logic.

import { useState } from 'react';
import { JsonTree } from "@gfazioli/mantine-json-tree";
import { Code, Stack, Text } from "@mantine/core";
import { data } from './data';

function Demo() {
  const [clicked, setClicked] = useState<{ path: string; value: unknown } | null>(null);
  const [copied, setCopied] = useState<string | null>(null);

  return (
    <Stack>
      <JsonTree
        data={data}
        defaultExpanded
        maxDepth={1}
        withCopyToClipboard
        title="Click a node or copy a value"
        onNodeClick={(path, value) => setClicked({ path, value })}
        onCopy={(copy) => setCopied(copy)}
      />

      {clicked && (
        <Text size="sm">
          Clicked: <Code>{clicked.path}</Code>
        </Text>
      )}

      {copied && (
        <Text size="sm">
          Copied: <Code>{copied.length > 50 ? `${copied.slice(0, 50)}…` : copied}</Code>
        </Text>
      )}
    </Stack>
  );
}

Keyboard Navigation

JsonTree inherits full keyboard navigation from Mantine's Tree component:

• Arrow Up/Down: Navigate between nodes
• Arrow Right: Expand a collapsed node or move to first child
• Arrow Left: Collapse an expanded node or move to parent (with allExpanded, always move to the parent)
• Space: Toggle node expansion
• Enter: Open the inline editor for the focused row (when editable is enabled). Editable values add no tab stop of their own, so a large tree stays one stop, as Mantine's Tree intends
• Ctrl+C / Cmd+C: Copy the focused node's value to clipboard (when withCopyToClipboard is enabled). With no node focused it falls back to the root, and it never intercepts the shortcut while a form control inside the component — such as the search input — holds focus.
• Enter on a "… N more items" row: reveal the next entries (maxDisplayLength)
• With structuralEdits: F2 renames the focused key, Delete / Backspace removes the focused row, Insert / + adds to it, and Alt + Arrow Up/Down moves an array item

Labels and Accessibility

Every string JsonTree renders or announces on its own comes from labels, so a tree can be translated without touching the component. Pass only the ones to change; the rest keep their English defaults.

The labels cover:

• Icon buttons: copy, copied, copy all, expand all, collapse all, a node's expand / collapse toggle, search, clear search, add, remove, move up and move down. Every icon button carries its label as its accessible name, so a screen reader announces "Copy" rather than an unnamed button. The toolbar's buttons also show it as a tooltip.
• Text on screen: "show more" / "show less", the "… N more items" row and the type badges of showValueTypes. moreItems is a function of the count and of the unit (items, keys or entries), for languages whose plurals follow different rules; typeBadge receives the built-in badge (int, float, bool…) and the value's type.
• Inline editors: the names of the new-key, rename and value inputs (rename and edit take the key), and their validation messages (keyExists, required, notANumber).

The search placeholder keeps its own prop, searchPlaceholder, and the key count badge its own keyCountBadgeLabel.

import { JsonTree } from '@gfazioli/mantine-json-tree';

const data = {
  ordine: 'A-1024',
  cliente: { nome: 'Ada', citta: 'Torino' },
  righe: ['tazza', 'maglietta', 'quaderno', 'penna', 'agenda', 'matita'],
  note: 'Consegna al piano terra, citofono interno 4',
};

function Demo() {
  return (
    <JsonTree
      data={data}
      title="ordine.json"
      withBorder
      defaultExpanded
      maxDepth={-1}
      rootName={false}
      indentWidth={20}
      withSearch
      withExpandAll
      withCopyAll
      withCopyToClipboard
      collapseStringsAfterLength={20}
      maxDisplayLength={4}
      searchPlaceholder="Filtra chiavi e valori..."
      labels={{
        copy: 'Copia',
        copied: 'Copiato',
        copyAll: 'Copia JSON',
        expandAll: 'Espandi tutto',
        collapseAll: 'Comprimi tutto',
        search: 'Cerca',
        showMore: 'mostra tutto',
        showLess: 'mostra meno',
        // Italian, unlike English, changes the noun and the adjective in the singular
        moreItems: (count, unit) => {
          const keys = unit === 'keys';
          return count === 1
            ? `… un altro ${keys ? 'campo' : 'elemento'}`
            : `… altri ${count} ${keys ? 'campi' : 'elementi'}`;
        },
      }}
    />
  );
}

Path Tooltip

Set showPathOnHover to display the full JSON path in a tooltip when hovering over any node. This is useful for identifying the exact path to a value in deeply nested structures. You can customize the tooltip behavior with the tooltipProps prop, which accepts all Tooltip props except label and children.

import { JsonTree } from "@gfazioli/mantine-json-tree";
import { data } from './data';

function Demo() {
  return (
    <JsonTree
      data={data}
      defaultExpanded
      maxDepth={-1}
      showPathOnHover
      title="Hover over any node to see its path"
    />
  );
}

Max Height

Use the maxHeight prop to limit the tree height and enable scrolling. This is useful for embedding the tree in layouts with limited vertical space.

import { JsonTree } from "@gfazioli/mantine-json-tree";
import { data } from './data';

function Demo() {
  return <JsonTree maxHeight={300} showIndentGuides data={data} defaultExpanded maxDepth={-1} />;
}

Controlled Expand State

Use the expanded and onExpandedChange props for controlled expand/collapse state. The onExpand and onCollapse callbacks fire for individual node toggling:

const [expanded, setExpanded] = useState<string[]>([
  'root',
  'root.settings',
]);

<JsonTree
  data={data}
  expanded={expanded}
  onExpandedChange={setExpanded}
  onExpand={(path) => console.log('Expanded:', path)}
  onCollapse={(path) => console.log('Collapsed:', path)}
/>;

Locked Expansion

allExpanded opens every node, array groups included, and keeps them open: the toggles and the expand/collapse all controls disappear, and neither the mouse nor the keyboard can collapse a node. It suits a static payload in documentation or a report. defaultExpanded, maxDepth and a controlled expanded are ignored while it is on.

import { JsonTree } from '@gfazioli/mantine-json-tree';

const data = {
  status: 201,
  body: {
    id: 'inv_2048',
    lines: [
      { sku: 'MUG-01', qty: 2 },
      { sku: 'TEE-XL', qty: 1 },
    ],
    customer: { name: 'Ada', country: 'UK' },
  },
};

function Demo() {
  return <JsonTree data={data} title="POST /invoices" withBorder allExpanded withExpandAll />;
}

Responsive size

The size prop supports responsive values using Mantine breakpoint objects. This allows you to set different font sizes based on the viewport width, using CSS media queries (no JavaScript re-renders):

<JsonTree data={data} size={{ base: 'xs', sm: 'sm', lg: 'md' }} />

Style the component with classNames

You can style the JsonTree component using the classNames prop to target specific inner elements. This allows for granular customization of the component's appearance.

import { JsonTree } from "@gfazioli/mantine-json-tree";
import { data } from './data';
import classes from './JsonTree.module.css';

function Demo() {
  return (
    <JsonTree
      classNames={classes}
      title="demo.json"
      showIndentGuides
      defaultExpanded
      showItemsCount
      maxDepth={1}
      data={data}
    />
  );
}

Styles API

JsonTree supports Styles API, you can add styles to any inner element of the component with classNames prop. Follow Styles API documentation to learn more.

You can customize the appearance of the JsonTree component using the Styles API. This allows you to modify styles for various parts of the component, such as keys, values, brackets, and more.

/*
 * Hover over selectors to apply outline styles
 *
 */