DisplayReact
A read-only tree of one value that came from JSON: objects and arrays open and close, and every other value shows its type.
Rendered by React 19.3.1
Loading React…Installation
npm i @hamur/reactNot on npm yet. The package goes out under the chosen name.
Anatomy
Import the component and assemble its parts:
<JsonTreeView.Root>
<JsonTreeView.Item>
<JsonTreeView.ItemContent>
<JsonTreeView.ItemToggle />
<JsonTreeView.Key />
<JsonTreeView.Value />
<JsonTreeView.Count />
</JsonTreeView.ItemContent>
<JsonTreeView.Group />
</JsonTreeView.Item>
</JsonTreeView.Root>Examples
Toolbar
Expand all and Collapse all through getJsonTreeViewContainerIds, and Copy value and Copy path for the focused item.
Search
A search field over keys and values, and the number of matches from onMatchCountChange.
Controlled
expanded held by the app: buttons open the address, close everything or reset, and the open ids are listed.
Large
An array of 1,250 records shown as 13 ranges of up to 100 members, each opened on its own.
Virtualized
5,000 records as a flat list with virtualized: only the rows in view are in the page.
Types
One value of each type, a big integer and a date among them, and a reference back to the whole value.
API reference
22 props across 8 parts, in React syntax. className, style, render are listed once, under Shared props.
CountJsonTreeView.Count
The number of members of the item's node: 3 keys for an object, 2 items for an array or a range. Renders nothing for a leaf, {} and [] included. Not in upstream (decision 73, docs/design/log/json-tree-view.md). Renders a <span>.
| Data attribute | Description |
|---|---|
data-type | The type of the node's value. |
GroupJsonTreeView.Group
The members of an item's node, each rendered by the Root's children function, shown while it is open. Renders nothing in a virtualized tree, whose rows are flat. Not in upstream (decision 73, docs/design/log/json-tree-view.md). Renders a <div>.
| Prop | Type | Default |
|---|---|---|
keepMountedWhether to keep the element in the DOM while the item is closed. | boolean | false |
hiddenUntilFoundAllows the browser's built-in page search to find and open the group's items. | boolean | false |
ItemJsonTreeView.Item
The item of a node, with its row (JsonTreeView.ItemContent) and its members (JsonTreeView.Group): Tree's item, named by its row and described by its type. Not in upstream (decision 73, docs/design/log/json-tree-view.md). Renders a <div>.
| Prop | Type | Default |
|---|---|---|
noderequiredThe node the Root's children function received. | JsonTreeViewNode | — |
| Data attribute | Description |
|---|---|
data-type | The type of the item's value. |
data-expanded | Present when the item is open. |
data-highlighted | Present when the item is highlighted (holds focus). |
data-leaf | Present when the item has no members. |
data-level | The depth of the item, from 1 at the top level. |
data-match | Present when the item matches the query, not when it is shown only as an ancestor of a match. |
| CSS variable | Description |
|---|---|
--tree-item-level | The depth of the item, from 1 at the top level: the indent of its row. |
ItemContentJsonTreeView.ItemContent
The row of an item: its toggle, indicator and text. Its text names the item. Renders a <div>.
ItemToggleJsonTreeView.ItemToggle
Opens and closes its item without selecting it. Hidden from assistive technology and not focusable: the item's keys do the same. Renders a <span>.
| Prop | Type | Default |
|---|---|---|
keepMountedWhether to render the toggle for leaves too, to align the rows. | boolean | false |
KeyJsonTreeView.Key
The key of the item's node: an object key as it is, an array index, or a range's label; matches of the query in a <mark>. Renders nothing for a keyless node. Not in upstream (decision 73, docs/design/log/json-tree-view.md). Renders a <bdi>.
| Data attribute | Description |
|---|---|
data-type | The type of the node's value. |
data-index | The index of an array member, from 0. Absent for an object key. |
RootJsonTreeView.Root
A read-only tree of one value that came from JSON: objects and arrays open and close, primitives show their type, and the focused value is copied with Ctrl/Cmd+C., followed by the status region and the type descriptions. Not in upstream (decision 73, docs/design/log/json-tree-view.md). Renders a <div>.
| Prop | Type | Default |
|---|---|---|
valuerequiredThe value shown. | unknown | — |
childrenrequiredThe row of a node: called for each top-level node, by each Group for its members, and by | (node: JsonTreeViewNode) => React.ReactNode | — |
expandedThe ids (JSON Pointers) of the open containers. | readonly string[] | — |
defaultExpandedThe ids of the containers open when the tree is initially rendered. | readonly string[] | — |
onExpandedChangeEvent handler called when containers open or close. | ((expanded: string[], eventDetails: TreeRootExpandedChangeEventDetails) => void) | — |
defaultExpandedDepthWithout expanded and defaultExpanded, the containers up to this level start open | number | 1 |
sortKeysWhether object keys are sorted (true: numeric-aware in the locale), or how. | JsonTreeViewSortKeys | false |
rangeThresholdAn array of more members shows ranges of them. | number | 100 |
queryThe search: matching items show with their ancestors, which open for the search only. | string | — |
queryTargetWhat the query matches: keys, primitive values, or both. | JsonTreeViewQueryTarget | 'all' |
onMatchCountChangeCalled with the number of matches 300 ms after the query last changed. | ((count: number) => void) | — |
copyableWhether Ctrl/Cmd+C on a focused item copies it. | boolean | true |
getCopyTextThe text an item copies, in place of getJsonTreeViewCopyText(node). | ((node: JsonTreeViewNode) => string) | — |
onItemCopyCalled after a copy settles, with the node, the text and the failure (null on success). | ((details: JsonTreeViewCopyDetails) => void) | — |
onHighlightChangeEvent handler called when the focused item changes. | ((node: JsonTreeViewNode | null) => void) | — |
virtualizedWhether only the rows near the scroll position render: a flat tree in a Virtualizer that | boolean | false |
loopFocusWhether Down on the last item moves to the first, and Up on the first to the last. | boolean | false |
labelsThe texts: type descriptions, counts, copy and match announcements, and Tree's. | JsonTreeViewRootLabels | — |
| Data attribute | Description |
|---|---|
data-orientation | Indicates the orientation of the tree. |
data-filtering | Present when query is not empty. |
data-empty | Present when the query matches nothing. |
ValueJsonTreeView.Value
The value of the item's node as text: a string with its quotes, numbers, true, null, {…} for a container; matches of the query in a <mark>. Renders nothing for a range. Not in upstream (decision 73, docs/design/log/json-tree-view.md). Renders a <bdi>.
| Data attribute | Description |
|---|---|
data-type | The type of the node's value. |
Shared props
Every part that renders an element takes these.
| Prop | Type |
|---|---|
classNameCSS class applied to the element, or a function that
returns a class based on the component's state. | string | ((state: State) => string | undefined) |
styleStyle applied to the element, or a function that
returns a style object based on the component's state. | React.CSSProperties | ((state: State) => React.CSSProperties | undefined) |
renderAllows you to replace the component's HTML element
with a different tag, or compose it with another component. | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, State> |
Keyboard and accessibility
Keyboard
| Keys | Does | Part |
|---|---|---|
| ArrowDownArrowUp | Moves focus to the next or previous visible item | Root |
| ArrowRightArrowLeft | Opens a closed container, then moves to its first member; moves to the parent, then closes it | Item |
| End | Moves focus to the last visible item and scrolls it in, also in a virtualized tree | Root |
| * | Opens every closed container among the focused item's siblings | Root |
| Moves focus to the next visible item whose key starts with what was typed | Root | |
| ControlCMetaC | Copies the focused item and says so; nothing happens while text inside the tree is selected | Item |
Accessibility
| Part | Sets | So that |
|---|---|---|
| Root | role="tree", aria-orientation, aria-keyshortcuts for the copy keys; named by aria-label or aria-labelledby | the value is read as one widget with its name; a development build warns without one |
| Root | one polite role="status" region next to the tree, and after it a hidden element with one description per type | "Copied", "Copy failed", the match count and "No matches" are announced, and the types have text to point at |
| Item | role="treeitem" with aria-level, aria-posinset and aria-setsize, from the data when virtualized | each item says where it is, also when its siblings are not mounted |
| Item | aria-expanded on containers only; no aria-selected or aria-checked, since nothing is selectable | the state is read with the item, and a leaf says nothing about opening |
| Item | named by its ItemContent, not by the text of its Group; aria-describedby points at the description of its type | an open object is read as "address", not as every key inside it, and "42" is "string" where 42 is "number" |
| Group | role="group" inside an open container | the members belong to their parent |
| ItemToggle | aria-hidden, never focusable | the chevron is for sight; the item's state says it |
| Key | a bdi element, the matched text in mark | a key in a right-to-left script keeps its direction inside the row |
| Value | a bdi element, the matched text in mark; nothing for a range | a value keeps its direction too, and the match is shown without changing the text |
| Count | text such as "3 keys" or "2 items"; nothing for a leaf or an empty container | the size of a container is read after its name |
Focus order
- The tree is one Tab stop: the focused item, or the first one. Nothing takes focus on mount.
- Inside, the arrow keys,
Endand typeahead move focus;Tableaves the tree from any item, and coming back returns to the last focused item. - Closing the parent of the focused item moves focus to that parent.