Patterns / Graph detail panel
A graph with a detail panel for the selected node
A graph shows how things connect; the facts about one thing don't fit on its node. Let the person select a node and show its details beside the graph, without leaving it.
Give GraphView onSelect and hold the selection in your app as activeId: each node is a button, and the selected one has aria-current. Beside it, render an aside named by the node's heading, with the facts in a DetailsList. A fact your app doesn't know is null, and the list says "Not known".
Focus stays on the node the person chose, so arrow keys still move through the graph. Because the panel changes somewhere else on the page, say so once with useAnnouncer. The panel's Close button puts focus back on the node it was about.
The components
- Graph viewProThe graph: nodes as buttons with `onSelect`, the selected one marked with `aria-current`, arrow keys along the arrows (Pro).
- Details listProThe selected node's facts as labelled rows; an unknown value reads "Not known" (Pro).
- useAnnouncerProSays once, politely, that the panel now shows the node's details (Pro).
- DiagramProFor a diagram the person only reads: the same nodes and arrows, with no selection (Pro).
See it working
The code
The graph and its panel: selection held by the app, announced once, and Close returning focus to the node.
"use client"
import * as React from "react"
import { GraphView, type GraphViewNode } from "@/components/candor/graph-view"
import { DetailsList } from "@/components/candor/details-list"
import { useAnnouncer } from "@/lib/candor/use-announcer"
import { Button } from "@/components/candor/ui/button"
/** One thing in your model, from your server. Unknown facts are null, and the panel says "Not known". */
type Thing = { id: string; name: string; kind: string; owner: string | null; changedAt: string | null; after: string[] }
export function ModelGraph({ things }: { things: Thing[] }) {
const [selectedId, setSelectedId] = React.useState<string | null>(null)
const graphRef = React.useRef<HTMLDivElement>(null)
const headingId = React.useId()
const announce = useAnnouncer()
const selected = things.find((thing) => thing.id === selectedId)
const nodes: GraphViewNode[] = things.map((thing) => ({
id: thing.id,
after: thing.after,
// The kind in words on the node, never only in how it is drawn.
content: (
<span className="flex flex-col items-start text-start">
<span className="font-medium">{thing.name}</span>
<span className="text-xs text-muted-foreground">{thing.kind}</span>
</span>
),
}))
function select(id: string) {
setSelectedId(id)
// Focus stays on the node the person chose; the panel's new contents are said once, politely.
const name = things.find((thing) => thing.id === id)?.name
if (name) announce(`Details for ${name} shown beside the graph`)
}
function close() {
// Back to the node the panel was about, so the keyboard carries on from where it was.
const node = graphRef.current?.querySelector<HTMLButtonElement>("button[aria-current]")
setSelectedId(null)
node?.focus()
}
return (
<div className="grid gap-4 md:grid-cols-[minmax(0,1fr)_20rem]">
<div ref={graphRef} className="min-w-0 overflow-auto">
<GraphView label="Data model" nodes={nodes} onSelect={select} activeId={selectedId ?? undefined} />
</div>
{selected && (
<aside aria-labelledby={headingId} className="flex flex-col gap-3 rounded-lg border p-4">
<div className="flex items-start justify-between gap-2">
<h2 id={headingId} className="text-sm font-semibold">
{selected.name}
</h2>
<Button size="sm" variant="ghost" onClick={close}>
Close details
</Button>
</div>
<DetailsList
headingLevel={3}
groups={[
{
id: "facts",
title: "About it",
collapsible: false,
rows: [
{ label: "Kind", value: selected.kind },
{ label: "Owner", value: selected.owner },
{ label: "Last changed", value: selected.changedAt },
],
},
]}
/>
</aside>
)}
</div>
)
}
Install
Each component brings in what it depends on. The free ones install as they are; Pro and Premium ones need a licence key.
Good to know
- Say each node's kind in words in its
content. Arrows, and anything else drawn only, aren't read, so the words carry it. - Don't move focus into the panel when a node is selected: the person may be walking the graph. Put the panel after the graph in the page, so Tab reaches it next.
- On a narrow screen the panel goes under the graph. Keep the announcement, since the panel may be out of view.