• Docs
  • Blog
    • 0.25.1

    • light

      dark

      system

      Switch mode
    • Cerberus

      Acheron

      Elysium

    Get Started
    Components
    Styling
    Theming

    Concepts

    OverviewCompositionTesting

    Layout

    Aspect RatioBleedBoxCenterContainerDividerFlexFloatGridLink OverlayScrollableStackWrap

    Components

    AccordionAdmonitionAvatarButtonCarouselCheckboxClipboardCollapsibleComboboxConfirm ModalCTAModalDate PickerDialogFieldFieldsetFile UploaderIcon ButtonInputLoading StatesMenuNotificationsNumber InputPin InputProgressPrompt ModalRadioRatingSelectSplit ButtonSwitchTableTabsTagTextTextareaToggleTooltip

    Utilities

    Client OnlyDownload TriggerEnvironmentFeature FlagsFocus TrapForFormat ByteFormat NumberFormat Relative TimeFrameHighlightJSON Tree ViewLocaleLocal StoragePortalPresenceShowsplitPropsTheme

    JSON Tree View

    A component that displays a JSON object in a tree-like structure.

    • npm
    • Ark

    Examples

    Learn how to use the JsonTreeView component in your project. Let's take a look at the most basic example:

    { name: "John Doe", age: 30, email: "john.doe@example.com", … }
    name: "John Doe"
    age: 30
    email: "john.doe@example.com"
    tags: (3) [ "tag1", "tag2", "tag3" ]
    0: "tag1"
    1: "tag2"
    2: "tag3"
    length: 3
    address: { street: "123 Main St", city: "Anytown", state: "CA", … }
    street: "123 Main St"
    city: "Anytown"
    state: "CA"
    zip: "12345"
    Copy
    'use client'
    import { JsonTreeView } from '@cerberus/react'
    import { ChevronRight } from '@carbon/icons-react'
    export const Basic = () => {
    return (
    <JsonTreeView.Root
    data={{
    name: 'John Doe',
    age: 30,
    email: 'john.doe@example.com',
    tags: ['tag1', 'tag2', 'tag3'],
    address: {
    street: '123 Main St',
    city: 'Anytown',
    state: 'CA',
    zip: '12345',
    },
    }}
    >
    <JsonTreeView.Tree arrow={<ChevronRight />} />
    </JsonTreeView.Root>
    )
    }

    Different Data Types

    The JSON tree view can display various JavaScript data types including objects, arrays, primitives, and special values:

    'use client'
    import { JsonTreeView } from '@cerberus/react'
    import { ChevronRight } from '@carbon/icons-react'
    const testArray = [1, 2, 3, 4, 5]
    Object.defineProperties(testArray, {
    customProperty: { value: 'custom value', enumerable: false, writable: false },
    anotherProperty: { value: 42, enumerable: false, writable: false },
    })
    export const ArrayData = () => {
    return (
    <JsonTreeView.Root
    data={{
    normalArray: [1, 2, 3],
    arrayWithNonEnumerableProperties: testArray,
    sparseArray: (() => {
    const sparse = []
    sparse[0] = 'first'
    sparse[5] = 'sixth'
    return sparse
    })(),
    }}
    >
    <JsonTreeView.Tree arrow={<ChevronRight />} />
    </JsonTreeView.Root>
    )
    }

    Functions and Methods

    Display JavaScript functions, async functions, and generators in your JSON tree:

    'use client'
    import { JsonTreeView } from '@cerberus/react'
    import { ChevronRight } from '@carbon/icons-react'
    const data = [
    function sum(a: number, b: number) {
    return a + b
    },
    async (promises: Promise<any>[]) => await Promise.all(promises),
    function* generator(a: number) {
    while (a > 0) {
    yield a - 1
    }
    },
    ]
    export const Functions = () => {
    return (
    <JsonTreeView.Root data={data}>
    <JsonTreeView.Tree arrow={<ChevronRight />} />
    </JsonTreeView.Root>
    )
    }

    Regular Expressions

    Regular expressions are displayed with their pattern and flags:

    'use client'
    import { JsonTreeView } from '@cerberus/react'
    import { ChevronRight } from '@carbon/icons-react'
    const data = {
    regex: /^[a-z0-9]+/g,
    case_insensitive: /^(?:[a-z0-9]+)foo.*?/i,
    }
    export const Regex = () => {
    return (
    <JsonTreeView.Root data={data}>
    <JsonTreeView.Tree arrow={<ChevronRight />} />
    </JsonTreeView.Root>
    )
    }

    Error Objects

    Error objects and their stack traces can be visualized:

    'use client'
    import { JsonTreeView } from '@cerberus/react'
    import { ChevronRight } from '@carbon/icons-react'
    const data = new Error('Error')
    export const Errors = () => {
    return (
    <JsonTreeView.Root data={data}>
    <JsonTreeView.Tree arrow={<ChevronRight />} />
    </JsonTreeView.Root>
    )
    }

    Map and Set Objects

    Native JavaScript Map and Set objects are supported:

    'use client'
    import { JsonTreeView } from '@cerberus/react'
    import { ChevronRight } from '@carbon/icons-react'
    const data = new Map<string, any>([
    ['name', 'ark-ui-json-tree'],
    ['license', 'MIT'],
    ['elements', new Set(['ark-ui', 123, false, true, null, undefined, 456n])],
    [
    'nested',
    new Map<string, any>([
    [
    'taglines',
    new Set([
    { name: 'ark-ui', feature: 'headless components' },
    { name: 'ark-ui', feature: 'framework agnostic' },
    { name: 'ark-ui', feature: 'accessible by default' },
    ]),
    ],
    ]),
    ],
    ])
    export const MapAndSet = () => {
    return (
    <JsonTreeView.Root data={data}>
    <JsonTreeView.Tree arrow={<ChevronRight />} />
    </JsonTreeView.Root>
    )
    }

    Controlling Expand Level

    Use the defaultExpandedDepth prop to control how many levels are expanded by default:

    'use client'
    import { JsonTreeView } from '@cerberus/react'
    import { ChevronRight } from '@carbon/icons-react'
    export const ExpandLevel = () => {
    return (
    <JsonTreeView.Root
    defaultExpandedDepth={1}
    data={{
    name: 'John Doe',
    age: 30,
    email: 'john.doe@example.com',
    tags: ['tag1', 'tag2', 'tag3'],
    address: {
    street: '123 Main St',
    city: 'Anytown',
    state: 'CA',
    zip: '12345',
    },
    }}
    >
    <JsonTreeView.Tree arrow={<ChevronRight />} />
    </JsonTreeView.Root>
    )
    }

    Custom Value Rendering

    You can customize how specific values are rendered using the renderValue prop. This example shows how to make email addresses clickable:

    'use client'
    import { JsonTreeView } from '@cerberus/react'
    import { ChevronRight } from '@carbon/icons-react'
    export const RenderValue = () => {
    return (
    <JsonTreeView.Root
    defaultExpandedDepth={2}
    data={{
    name: 'John Doe',
    age: 30,
    number: Number.NaN,
    email: 'john.doe@example.com',
    address: {
    street: '123 Main St',
    city: 'Anytown',
    state: 'CA',
    zip: '12345',
    },
    }}
    >
    <JsonTreeView.Tree
    arrow={<ChevronRight />}
    renderValue={(node) => {
    if (node.type === 'text' && typeof node.value === 'string' && isEmail(node.value)) {
    return (
    <a href={`mailto:${node.value}`} target="_blank" rel="noreferrer">
    {node.value}
    </a>
    )
    }
    }}
    />
    </JsonTreeView.Root>
    )
    }
    const isEmail = (value: string) => {
    const strippedValue = value.replace(/^"(.*)"$/, '$1')
    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(strippedValue)
    }

    Configuration Options

    The JSON tree view supports several configuration options to customize the display:

    <JsonTreeView.Root
    data={data}
    defaultExpandedDepth={2}
    quotesOnKeys={true}
    showNonenumerable={true}
    maxPreviewItems={5}
    collapseStringsAfterLength={50}
    groupArraysAfterLength={100}
    >
    <JsonTreeView.Tree arrow={<ChevronRight />} />
    </JsonTreeView.Root>

    Configuration Options:

    • quotesOnKeys: Whether to show quotes around object keys
    • showNonenumerable: Whether to show non-enumerable properties
    • maxPreviewItems: Maximum number of items to show in object/array previews
    • collapseStringsAfterLength: Collapse strings longer than this length
    • groupArraysAfterLength: Group array items when array is longer than this length

    Using the Root Provider

    The RootProvider component provides a context for the JSON tree view. It accepts the value of the useJsonTreeView hook. You can leverage it to access the component state and methods from outside the JSON tree view.

    'use client'
    import { JsonTreeView, useJsonTreeView } from '@cerberus/react'
    import { ChevronRight } from '@carbon/icons-react'
    export const RootProvider = () => {
    const jsonTreeView = useJsonTreeView({
    data: {
    name: 'John Doe',
    age: 30,
    email: 'john.doe@example.com',
    tags: ['tag1', 'tag2', 'tag3'],
    address: {
    street: '123 Main St',
    city: 'Anytown',
    state: 'CA',
    zip: '12345',
    },
    },
    })
    return (
    <JsonTreeView.RootProvider value={jsonTreeView}>
    <JsonTreeView.Tree arrow={<ChevronRight />} />
    </JsonTreeView.RootProvider>
    )
    }

    If you're using the RootProvider component, you don't need to use the Root component.

    API Reference

    PropTypeRequiredDescription
    asChildbooleanNoUse the provided child element as the default rendered element, combining their props and behavior.
    canRename(node: JsonNode<any>, indexPath: IndexPath) => booleanNoFunction to determine if a node can be renamed
    checkedValuestring[]NoThe controlled checked node value
    collapseStringsAfterLengthnumberNo
    data{}NoThe data to display in the tree.
    defaultCheckedValuestring[]NoThe initial checked node value when rendered.
    Use when you don't need to control the checked node value.
    defaultExpandedDepthnumberNoThe default expand level.
    defaultExpandedValuestring[]NoThe initial expanded node ids when rendered.
    Use when you don't need to control the expanded node value.
    defaultFocusedValuestringNoThe initial focused node value when rendered.
    Use when you don't need to control the focused node value.
    defaultSelectedValuestring[]NoThe initial selected node value when rendered.
    Use when you don't need to control the selected node value.
    expandedValuestring[]NoThe controlled expanded node ids
    expandOnClickbooleanNoWhether clicking on a branch should open it or not
    focusedValuestringNoThe value of the focused node
    groupArraysAfterLengthnumberNo
    idsPartial<{ root: string; tree: string; label: string; node: (value: string) => string }>NoThe ids of the tree elements. Useful for composition.
    lazyMountbooleanNoWhether to enable lazy mounting
    loadChildren(details: LoadChildrenDetails<JsonNode<any>>) => Promise<JsonNode<any>[]>NoFunction to load children for a node asynchronously.
    When provided, branches will wait for this promise to resolve before expanding.
    maxPreviewItemsnumberNo
    onBeforeRename(details: RenameCompleteDetails) => booleanNoCalled before a rename is completed. Return false to prevent the rename.
    onCheckedChange(details: CheckedChangeDetails) => voidNoCalled when the checked value changes
    onExpandedChange(details: ExpandedChangeDetails<JsonNode<any>>) => voidNoCalled when the tree is opened or closed
    onFocusChange(details: FocusChangeDetails<JsonNode<any>>) => voidNoCalled when the focused node changes
    onLoadChildrenComplete(details: LoadChildrenCompleteDetails<JsonNode<any>>) => voidNoCalled when a node finishes loading children
    onLoadChildrenError(details: LoadChildrenErrorDetails<JsonNode<any>>) => voidNoCalled when loading children fails for one or more nodes
    onRenameComplete(details: RenameCompleteDetails) => voidNoCalled when a node label rename is completed
    onRenameStart(details: RenameStartDetails<JsonNode<any>>) => voidNoCalled when a node starts being renamed
    onSelectionChange(details: SelectionChangeDetails<JsonNode<any>>) => voidNoCalled when the selection changes
    quotesOnKeysbooleanNoWhether to show quotes on the keys.
    selectedValuestring[]NoThe controlled selected node value
    selectionMode`'single''multiple'`No
    • "single": only one node can be selected
    • "multiple": multiple nodes can be selected | | showNonenumerable | boolean | No | | | typeahead | boolean | No | Whether the tree supports typeahead search | | unmountOnExit | boolean | No | Whether to unmount on exit. |

    JsonTreeViewRootProvider Props:

    PropTypeRequiredDescription
    valueUseTreeViewReturn<JsonNode<any>>Yes
    asChildbooleanNoUse the provided child element as the default rendered element, combining their props and behavior.
    lazyMountbooleanNoWhether to enable lazy mounting
    unmountOnExitbooleanNoWhether to unmount on exit.

    JsonTreeViewTree Props:

    PropTypeRequiredDescription
    arrowReactNodeNoThe icon to use for the arrow.
    asChildbooleanNoUse the provided child element as the default rendered element, combining their props and behavior.
    indentGuideanyNoThe indent guide to use for the tree.
    renderValue(node: JsonNodeHastElement) => ReactNodeNoThe function to render the value of the node.

    Accessibility

    The JSON tree view is built on top of the Tree View component and complies with the Tree View WAI-ARIA design pattern.

    On this page

    • Edit this page on Github
    Cerberus Design System | Docs