HelixOverviewComponentsMapsGraphIntroductionInstallationDeriving a themeSandboxTheme builderVisual testingCortexDocsEngramActiveTraceActiveRecallActiveServicesInsightsGet in touchSource on GitHub
Essentials
GraphsHelix Graph puts a frame around a graph drawn by Sigma.js, cosmos.gl, three.js,
a renderer of your own, or Helix's own isometric diagram. The frame adds a searchable list of every note, zoom
and fullscreen buttons, and keyboard controls. You give the frame notes and
links, and @fusion.dev/helix-graph draws them with the renderer, colored by
your theme.Add a graphInstall Helix, the graph connector, and Sigma.js with its layout:bun add @fusion.dev/helix @fusion.dev/helix-graph sigma graphology graphology-layout-forceatlas2Add the frame, with an element inside it for the renderer to draw in:<helix-graphlabel="Research notes"><div></div></helix-graph>Give the frame its notes and links, make the renderer, and connect the two:import'@fusion.dev/helix/graph'import{connectGraph}from'@fusion.dev/helix-graph'import{sigmaDriver,sigmaOptions}from'@fusion.dev/helix-graph/sigma'importGraphfrom'graphology'importforceAtlas2from'graphology-layout-forceatlas2'importFA2Layoutfrom'graphology-layout-forceatlas2/worker'importSigmafrom'sigma'constframe=document.querySelector('helix-graph')frame.nodes=[{id:'roadmap',label:'Roadmap',group:'Product'},{id:'pricing',label:'Pricing',group:'Sales'},]frame.links=[{source:'pricing',target:'roadmap'}]constsigma=newSigma(newGraph(),frame.querySelector('div'),sigmaOptions())constconnection=connectGraph(frame,sigmaDriver(sigma,{layout:(graph)=>newFA2Layout(graph,{settings:forceAtlas2.inferSettings(graph)}),}),)nodes and links are properties. Set them in JavaScript, since a graph of
thousands of notes written as markup would be thousands of elements.What the connector doesconnectGraph links the frame to the renderer:
It draws the notes and links, and lays out the notes that have no place.
It colors each group from your theme's series colors, and the names in your
theme's typeface. It recolors the graph when your theme or mode changes.
After you replace a stylesheet, which changes no attribute, call
connection.restyle().
The note you select in the list is the note selected in the drawing, and the
other way round. The selected note's links stand out, and the rest of the
graph fades.
The frame's zoom buttons and keys move the drawing.
connection.relayout() lays the whole graph out again.
connection.disconnect() puts back everything connectGraph changed.
Choose a rendererRendererUse it forInstallDriverSigma.jsGraphs of thousands of notessigma graphology graphology-layout-forceatlas2sigmaDriver from @fusion.dev/helix-graph/sigmacosmos.glGraphs of tens of thousands of notes or more, laid out on the GPU@cosmos.gl/graphcosmosDriver from @fusion.dev/helix-graph/cosmosthree.jsGraphs in 3D, and graphs on the surface of a 3D modelthree d3-force-3dthreeDriver from @fusion.dev/helix-graph/threeHelix, in SVGArchitecture and flow diagrams of up to a few hundred notes, drawn as solids on an isometric floorNothing moreisometricDriver from @fusion.dev/helix-graph/isometricNone of the renderers is bundled with Helix, so you can use the version you
already have.With cosmos.gl, make the graph in the frame's box and pass the box as well:import{Graph}from'@cosmos.gl/graph'import{cosmosDriver}from'@fusion.dev/helix-graph/cosmos'constbox=frame.querySelector('div')constgraph=newGraph(box,{attribution:'',enableSimulation:true,scalePointsOnZoom:false})constconnection=connectGraph(frame,cosmosDriver(graph,box))With three.js, pass the box, and the driver makes the renderer:import{threeDriver}from'@fusion.dev/helix-graph/three'constconnection=connectGraph(frame,threeDriver(frame.querySelector('div')))Drag to turn a 3D graph, and use the wheel or a pinch to zoom. It turns slowly
on its own for its first five seconds, and stops as soon as someone handles it.
It does not turn for a reader who asked for reduced motion. Set
autoRotate: false to keep it still.A 3D graph draws only while something moves. Every 3D graph on a page shares
six WebGL contexts: past six, a graph far off screen gives its context back
and takes it again as it comes near.Draw an isometric diagramisometricDriver draws the graph as an isometric diagram in SVG, with nothing
more to install. Pass it the box:import{isometricDriver}from'@fusion.dev/helix-graph/isometric'frame.nodes=[{id:'gateway',label:'API gateway',group:'Edge',x:0,y:0},{id:'orders',label:'Orders',group:'Services',x:3,y:0},{id:'ledger',label:'Order ledger',group:'Data',shape:'circle',x:6,y:0},]frame.links=[{source:'gateway',target:'orders'},{source:'orders',target:'ledger'},]constconnection=connectGraph(frame,isometricDriver(frame.querySelector('div')))
Each note stands on a cell of the floor at its x and y: x runs
across, and y runs back. When no note gives a place, the driver lays the
notes out in columns along the links, sources first. A note added without a
place goes to the nearest free cell beside the notes it links to.
A note's shape picks its solid.square is a block, which is the
default, circle is a cylinder, and diamond is a pyramid. Its size sets
its height.
Each face is shaded from the note's color, so the diagram takes your
theme. Each group stands on a plate of its color, with its name written on
the floor.
Links run along the floor, with an arrow halfway that points the way the
link runs.
Drag to pan, and use the wheel to zoom. Set flat: true to draw every note at
no height. The drawing moves only when the reader moves it, so there is no
motion to pause.Turn and tilt the viewturn is the compass bearing the diagram is seen from, in degrees, and tilt
is the camera's height above the floor. The defaults are the isometric view:
turn: 45, the front left corner, and tilt: 35.26. tilt runs from 15 to
90, which is a plan seen from straight above.constdriver=isometricDriver(box,{turn:20,tilt:55})connectGraph(frame,driver)driver.turnBy(90)// brings the next corner round to the frontdriver.turnTo({tilt:90})// looks from straight above
The faces and the light follow the camera. Each solid shows the faces
turned toward the camera, and the light falls from the upper left of the
page.
A diagram seen whole stays whole as it turns. Otherwise the view turns
about the middle of the box.
Shift with a drag turns the view across and tilts it up and down.
turnBy and turnTo animate, unless the reader asked for reduced
motion.
Give your turn buttons labels that name the diagram, such as "Turn the diagram
left".Free the rendererCall connection.disconnect() when the graph leaves the page, then free the
renderer you made:connection.disconnect()sigma.kill()// Sigma.jsgraph.destroy()// cosmos.glthreeDriver makes its own renderer, and disconnect() frees it. A graph you
remove from the page without disconnecting keeps its renderer running.Keep the layoutA layout places every note that has no x and y, and moves only those. When
it settles, the frame sends helix-graph-layout with where each note ended.
Save the positions and pass them back as each note's x and y, and the graph
opens in the same places next time, with no layout to wait for:frame.addEventListener('helix-graph-layout',(event)=>{localStorage.setItem('positions',JSON.stringify(event.detail.positions))})Update the graph as your data changesGive the frame new arrays whenever your data changes. The connector compares
them with what is drawn, by each note's id and each link's two ends, and
draws only what changed. New notes grow in beside their neighbors, and the rest
stay where they are:socket.addEventListener('message',({data})=>{constnote=JSON.parse(data)frame.nodes=[...frame.nodes,note]frame.links=[...frame.links,{source:note.id,target:note.parent}]})Call signal() to show something passing between two notes, such as a message
or a payment. A comet travels along the link between them, in the first note's
color turning to the second's, or in the color of a tone you give it:frame.signal('checkout','payments',{tone:'success'})When someone asked for reduced motion, the link lights up for a moment
instead. Screen readers do not announce signals, so say anything a reader needs
to know in your page's own words as well.Style the notesEach note takes these fields, as Helix's other components do:FieldValuesWhat it doesgroupAny nameColors the note from your theme's series. Each group's name is drawn over its notesshapecircle, square, diamond, ringSays what kind of note it is at a glanceemphasissolid, outlined, subtleFills the note, rings it, or tints itmaterialglass, frostedDraws the note as a shaded sphere or as frosted glasstoneprimary, accent, info, success, warning, danger, neutralColors the note by what it means, over its group's colorsizeA numberHow large the note is. A note without one is as large as it is connectedSet a default for every note with the driver's options, such as
sigmaDriver(sigma, { material: 'glass', shape: 'circle' }). cosmos.gl draws a
note's shape and not its emphasis or material.Show a legendSet legend to name the groups over the drawing, each in its color. Each name
is a button that shows or hides the group's notes, in the drawing and in the
list:<helix-graphlabel="Company notes"legend><div></div></helix-graph>hiddenGroups holds the names of the groups turned off. Set it to start with
some hidden. A press sends helix-before-graph-filter first, with every group
that would be hidden. Cancel it to keep the groups as they were, or to keep them
in your own state and set hiddenGroups yourself. helix-graph-filter follows
once the groups have changed, with every group now hidden:frame.addEventListener('helix-before-graph-filter',(event)=>{event.preventDefault()frame.hiddenGroups=event.detail.hidden})The legend is drawn where the notes have two groups or more. On a frame
narrower than 40rem it is one row, which scrolls.Find groups in the linksNotes without a group are drawn in one color. Where your data has no groups,
groupByCommunity finds them in the links: notes that link mostly to each other
become one group, named after its most linked note. Hand its result to the frame,
and the drawing colors the groups and the legend names them:import{groupByCommunity}from'@fusion.dev/helix-graph'frame.nodes=groupByCommunity(notes,links)frame.links=linksA note that has a group keeps it. Communities of fewer than three notes share
one group, named Other. Set fewest and rest to change either. The same
notes and links give the same groups every time. On 20,000 notes it takes about
65 milliseconds.Select a notePressing a note selects it, and pressing where no note is clears the selection.
The frame sends helix-activate with the note's id, and its active
property holds the selected note. Set active to select a note from your page,
and the frame brings it into view with its neighbors. Start with one selected
with default-active:<helix-graphdefault-active="roadmap"label="Research notes"><div></div></helix-graph>To keep the selection in your own state, cancel helix-before-activate and set
active yourself.Set depth to show only the notes within that many links of the selected one,
for a graph too large to read at once:<helix-graphdefault-active="roadmap"depth="2"label="Research notes"><div></div></helix-graph>The selected note lights the notes it links to and from. Pass reach to
connectGraph to light more: upstream lights every note a path of links
leads from to the selected one, and downstream every note a path leads to
from it. Where each link runs from what a note was derived from to the note,
upstream lights everything the note came from:connectGraph(frame,sigmaDriver(sigma),{reach:'upstream'})Draw the notes in a shapePass a stencil and the connector places the notes in its shape from the first
frame, with no layout. Each group takes a region of the shape. Give it an SVG
path and the size of the box it is drawn in:connectGraph(frame,driver,{stencil:{path:outline.getAttribute('d')??'',width:220,height:170},})@fusion.dev/helix-graph/shapes makes shapes from what you have:FunctionMakesshapeFromSvg(svg)A shape from an SVG's paths, rectangles, circles, ellipses, and polygonsshapeFromImage(image)A shape from an image's opaque pixelsshapeFromPath(path, width, height)A shape from one SVG pathinflate(shape, { depth })A solid from a flat shape, puffed out as a cushion isonSphere(shape)A flat map wrapped around a globesphere(), torus(), cuboid()SolidsWith three.js, place the notes on the surface of a 3D model.
shapeFromModel reads a .glb or .gltf file, and is in its own entry,
@fusion.dev/helix-graph/model, since it loads three.js. It reads a model
compressed with meshopt, as gltfpack writes one, which is often a third of
the size:import{shapeFromModel}from'@fusion.dev/helix-graph/model'constbrain=awaitshapeFromModel('/models/brain.glb')connectGraph(frame,threeDriver(box),{stencil:{...brain,place:'surface',regions:{Vision:'occipital',Hearing:'temporal'},},})
place: 'surface' puts the notes in a thin shell just inside the surface,
and draws the model under them. place: 'fill', the default, puts them all
through it.
regions sends each group to a named part of the shape. A model's parts are
its meshes, and an SVG's are its shapes with an id. A part the shape does
not have is reported in the console, with the parts it has.
In TypeScript, write place: 'surface' as const, so the object keeps the
type the stencil takes.
Share the scroll with the pageBy default a graph takes every gesture over it: the wheel zooms it, and one
finger moves it. A graph embedded in a page takes the wheel from a reader who
is scrolling past it. Set gestures on the frame to share them:<helix-graphgestures="cooperative"label="Research notes"><div></div></helix-graph>
cooperative leaves the wheel and one finger to the page. The graph takes
Ctrl or ⌘ with the wheel, and two fingers, and says so when a gesture passes
to the page. Use it for a graph embedded in a page.
activate takes nothing until the graph is pressed, and gives the gestures
back on Escape, when the pointer leaves, or on a press elsewhere.
always, the default, takes every gesture.
The keyboard and the frame's buttons work the same in every mode.Show the graph largeSet no-panel to leave the search and the list out of the frame, so the
drawing takes all of it, as at the top of a page. A Notes button among the
controls opens them over the drawing:<helix-graphgestures="cooperative"label="Research notes"no-panel><div></div></helix-graph>Set the frame's height with --graph-block-size, and the list's width with
--graph-panel-size.Show the graph once it is drawnWhen the layout settles, the frame sends helix-graph-ready and matches
:state(ready). Its ready property is true from then on. To show a graph
only once it is laid out, fade it in on the state:helix-graph>div{opacity:0;transition:opacity0.3s;}helix-graph:state(ready)>div{opacity:1;}Use the fade where the layout settles in a moment, such as a graph whose notes
all have places. Leave a cosmos.gl graph shown. Its layout runs for several
seconds by design, and the view follows the notes as they spread, so the reader
watches the graph settle. Faded in on the state, its drawing is hidden for that
whole time.Draw the graph before it loadsgraphSnapshot(nodes, links, options) draws the graph on your server as an
SVG, fitted to its box as Sigma.js fits it and in your theme's colors. Put it
in the frame after the element the renderer draws in, and the page shows a
graph from its first paint. connectGraph fades it out once the renderer has
drawn the graph whole.import{graphSnapshot}from'@fusion.dev/helix-graph/snapshot'constsnapshot=graphSnapshot(nodes,links,{height:540,labels:'all',width:1200,})// Inside helix-graph, after <div id="drawing"></div>, write the snapshot's markup.Give the snapshot the options you give the renderer, and it lines up with the
drawing that replaces it:
labels, groupLabels, shape, and emphasis, as sigmaDriver takes them.
active and reach, as the frame and connectGraph take them, to draw the
selection lit.
bounds, the box you hand Sigma's setCustomBBox, where you hand it one.
width and height are the box it is drawn for, and a smaller box shows its
middle. Every note needs an x and a y, since only a layout run in the
browser could place one without. The snapshot is an empty string where a note
has no place, so it is whole or absent. Its colors are your theme's tokens, so
it is light or dark with the page and follows a theme change.In a framework that renders the markup for you, such as React, put the snapshot
in an element that is a direct child of the frame and has the
data-helix-graph-snapshot attribute. connectGraph hides that element, and
leaves removing it to your framework.Keyboard and screen readers
The frame is one tab stop. Arrow keys move the drawing, and the plus and
minus keys zoom it. Set controls="pan zoom fullscreen" to add buttons that
move it. The buttons are a toolbar and one tab stop, and arrow keys move
between them by where they sit.
The list is a listbox, named by notes-label. Arrow keys, Home, End, Page
Up, and Page Down move through it, typing a letter moves to the next note
whose name starts with it, and Enter or Space selects a note.
The search field is a combobox that controls the list. Down and Up move
through the notes while the focus stays in the field, which names the note
the keys are on as its aria-activedescendant. Page Down and Page Up move a
page, and Enter selects the note. Typing, Left, Right, Home, and End go back
to the text. Escape first lets go of the note, then empties the search. With
no-panel, Escape on an empty search closes the list.
Alt and the arrow keys walk the links from the note the keys are on, in the
list or in the search field. Alt+Right follows a link to the first note it
links to or from. Alt+Down and Alt+Up move to the next or the previous note
linked to the note the step came from, and wrap. Alt+Left goes back along
the links walked. Right and Left swap on a right-to-left page. Screen
readers hear each note, how it stands to the note it came from, and its
place among that note's links, such as "Hiring plan. Linked from Roadmap. 2
of 3", from walk-label. A note with no links says so, from
link-count-label. Enter selects the note the walk reached.
While the list or the search field has the keys, the drawing marks the note
they are on as it marks the note under the pointer, with its name boxed and
its links lit, and a walk brings each note it reaches into view.
sigmaDriver draws the mark, and a driver of your own reads keyed from
the looks it is given.
The legend is a toolbar and one tab stop. Arrow keys, Home, and End move
between its groups, typing a letter moves to the next group whose name
starts with it, and Space or Enter shows or hides a group.
Screen readers read the selected note first, then how each other note links
to it, such as "Linked from Roadmap". They hear the count when a search or
the legend changes it.
When you select a note, in the list or in the drawing, screen readers hear
its name and how many notes the list holds, such as "Roadmap, selected. 4
notes", from selection-label. A selection your page writes to active is
not said.
After the arrow keys, plus, minus, or the buttons move the drawing, screen
readers hear which way it went, such as "Moved right" or "Zoomed in".
connectGraph tells the frame once the drawing has moved. If you answer
helix-graph-pan and helix-graph-zoom yourself, call frame.moved() once
your view has moved.
When you change nodes or links, the list keeps the note the keys are on.
When that note is removed, the keys move to the note that took its row.
Change the words with search-label, count-label, selected-label,
selection-label,
links-to-label, linked-from-label, linked-both-label, walk-label,
link-count-label,
moved-up-label, moved-down-label, moved-left-label,
moved-right-label, zoomed-in-label, and zoomed-out-label, or register
them for a language with registerWords (see
Localization).
EventsThe frame sends these events. Their names follow Map's: helix-graph-pan,
helix-graph-zoom, helix-graph-ready, and helix-graph-part-change match
helix-map-pan, helix-map-zoom, helix-map-ready, and
helix-map-part-change. These are the names Graph keeps.EventSent whenCancelableWho listenshelix-before-activateA note is about to be selectedYesYou, to keep the selection in your own statehelix-activateA note was selected, in the list or the drawingNoYouhelix-before-graph-filterA group in the legend was pressed, before its notes are shown or hiddenYesYou, to set hiddenGroups yourselfhelix-graph-filterA group's notes were shown or hiddenNoYouhelix-graph-layoutA layout settled, with where it put each noteNoYou, to keep the positionshelix-graph-readyThe graph has been drawn wholeNoYou, to show the graph once it is finishedhelix-graph-panAn arrow key or a pan button asked the drawing to moveNoconnectGraph, or your own rendererhelix-graph-zoomPlus, minus, or a zoom button asked the drawing to zoomNoconnectGraph, or your own rendererhelix-graph-part-changeThe notes, links, selection, depth, or gestures changedNoconnectGraph only. It stays on the frame.helix-graph-signalsignal() was calledNoconnectGraph only. It stays on the frame.Write a driverTo use another renderer, write a driver: an object with four methods.
draw({ nodes, links }) draws the graph, each note at its x and y.
look(looks) says how each note and link is drawn, from the theme, the
selection, and the note the keys are on, looks.keyed.
panBy(x, y, animate) moves the view by a number of pixels.
zoomBy(direction, animate) zooms in for 1 and out for -1.
Each optional method turns on a feature:MethodTurns onupdateDrawing only what changed, for live datasettleLaying out notes that have no placeonPressSelecting a note by pressing it in the drawingcenter, fitBringing a selected note and its neighbors into viewsignalSignals between notesgroupsEach group's name over its notesgestures, focusTargetSharing gestures with the page, and the frame's keysshapeDrawing a stencil's shapestopRemoving what the driver added when the graph disconnects