HelixOverviewDocsComponentsSandboxTheme builderCortexDocsEngramBuildingTraceBuildingRecallDeclaredServicesInsightsGet in touchSource on GitHub
Loading the reference
CanvasView SourceEdit in SandboxView MarkdownCopy MarkdownOpen in ClaudeOpen in CursorA board of cards and the connections between them, which a reader can walk, rearrange and connect.ExperimentalSince 0.100.0MediaUsageimport'@fusion.dev/helix/canvas'import'@fusion.dev/helix-headless/canvas'Preview
API ReferenceRoothelix-canvasA board of cards and the connections between them, which a reader can walk, rearrange and connect.
PropTypeDefaultDescriptioncomesFromLabelstring"from {cards}"How a card says where its connections come from, with `{cards}`.connectedLabelstring"Asked to connect {from} to {to}."What it says when a connection is asked for, with `{from}` and `{to}`.connectingLabelstring"Connecting from {from}. Move to another card and press Enter, or Escape to stop."What the live region says when a reader starts a connection, with `{from}`
filled in.connectionLabelstring"From {from} to {to}"What a connection is called, with `{from}` and `{to}`.controlsstringWhich of the controls this surface draws, as a list of what to keep.controlsLabelstringWhat the group of controls is called, for a reader who meets it.controlsPlacement"top-start"|"top-end"|"bottom-start"|"bottom-end"Which corner the controls sit in.fullscreenLabelstring"Fill the screen"What the control that fills the screen is called.grid"lines"|"dots"Rules the plane, so a reader can see it move.idleDelaynumber0How long the reader may be still before the chrome hides, in milliseconds.labelstring""Accessible name for the board, which is the one thing a consumer must write.labelEditorLabelstring"Label for {name}"What the field a label is edited in is called, with `{name}` for what it
labels.leadsToLabelstring"leads to {cards}"How a card says where its connections go, with `{cards}` as the list.order"spatial"|"edges"The order a reader meets the cards in.panDownLabelstring"Pan down"What the control that pans down is called.panLeftLabelstring"Pan left"What the control that pans left is called, on screen.panRightLabelstring"Pan right"What the control that pans right is called, on screen.panStepnumber0.25How far one press moves the view, as a fraction of what is on screen.panUpLabelstring"Pan up"What the control that pans up is called.path"straight"|"step"How every connection travels, where it does not say: `straight`, or `step`
for right angles.readOnlybooleanfalseKeeps every card where its author put it.reconnectingLabelstring"Moving the end of the connection from {from} to {to}. Move to a card and press Enter, or Escape to stop."What the live region says when a reader picks up a connection's end, with
`{from}` and `{to}`.selectedstring""The cards and connections the reader selected, by name, comma separated,
and empty for none.separation"outlined"|"plain"How the board stands off the page: `plain` for no frame at all.stoppedLabelstring"Stopped connecting."What it says when a reader stops connecting without asking.viewCanvasViewWhere the board is looking: the document's point at the middle of the view,
and the zoom.zoomInLabelstring"Zoom in"What the control that zooms in is called.zoomOutLabelstring"Zoom out"What the control that zooms out is called.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescriptionemptyWhat to show where the document has no nodes.footerChrome below the board.headerChrome above the board.
EventTypeDescriptionhelix-before-moveHelixBeforeMoveEventCards are about to move. Refuse it to keep the positions in your own state.helix-before-reconnectHelixBeforeReconnectEventA connection's end is about to move to another card or side. Refuse it to keep connections in your own state.helix-before-relabelHelixBeforeRelabelEventA connection's label or a group's name is about to change. Refuse it to keep labels in your own state.helix-canvas-editHelixCanvasEditEventThe reader asked to edit a card: a double-click, or Enter or F2. Open your own editor for it.helix-canvas-panHelixCanvasPanEventThe board was moved a step, by its controls or the arrow keys: a fact rather than a request. A drag says so through `helix-canvas-view`.helix-canvas-viewHelixCanvasViewEventWhere the board is looking changed, however it changed. The detail is the new view.helix-canvas-zoomHelixCanvasZoomEventThe board zoomed a step, by its controls or the keys. A wheel or a pinch says so through `helix-canvas-view`.helix-connectHelixConnectEventA reader asked for two cards to be joined. Add the `helix-canvas-edge` to do it.helix-moveHelixMoveEventCards moved and the move is finished: a drag let go, a click that put a card down, or a key pressed.helix-reconnectHelixReconnectEventA connection's end moved, and the move is finished.helix-relabelHelixRelabelEventA connection's label or a group's name changed.helix-removeHelixRemoveEventA reader asked for cards or connections to go. Remove the elements it names.helix-selectHelixSelectEventThe selection changed. The detail's `value` is the names, comma separated, empty for none. Cancelable: refusing it keeps the selection where it was.
MethodTypeDescriptionfit() => voidFits the whole board into the box, centered, and never magnified past its
own size.pan(to: ViewportWay) => voidAsks for the view to move, which the consumer answers.show(name: string) => voidBrings a card, by name, to the middle of the viewport.toggleFullscreen() => voidFills the screen with the surface, or comes back.toJsonCanvas() => CanvasDocumentThe board as a JSON Canvas document, for saving it.zoom(by: number) => voidAsks for the view to zoom, `1` in and `-1` out.
PartDescriptionarrowThe head an edge carries at an end that has one.boardThe plane the cards are placed on, which is what pans and zooms.controlsThe group the pan and zoom buttons sit in.draftThe connection being drawn, before it is asked for.edgeOne connector between two cards.edge-endAn end of a selected connection, which a press picks up, a click as well as a drag.edge-targetThe wider, unpainted line over a connector that a reader focuses and presses.edgesThe layer the connectors are drawn in.footerThe strip below the board.fullscreenThe button that fills the screen.headerThe strip above the board.labelThe label on a connector.label-editorThe field a connection's label or a group's name is edited in, where it sits.liveWhat the board says while a connection is being made, for a screen reader.marqueeThe box a Shift-drag across the empty board draws, which selects the cards it touches.pan-downThe button that moves the board down.pan-endThe button that moves the board the way the text ends.pan-startThe button that moves the board the way the text starts.pan-upThe button that moves the board up.regionThe named region the board is drawn in.viewportThe box the board is drawn inside.zoom-inThe button that zooms in.zoom-outThe button that zooms out.
CSS PropertyDescription--canvas-background-colorThe well behind the board.--canvas-block-sizeHow tall the frame is.--canvas-border-colorColor of the frame's edge.--canvas-edge-colorColor of a connector with no tone. Written in an edge's own `style`, it colors that edge alone.--canvas-edge-target-widthHow wide a connector is to a pointer, which is wider than it is drawn.--canvas-grid-sizeHow far apart the ruling is, in the document's own units, so it scales with the zoom.--canvas-handle-sizeHow large the ends of a selected connection are, one name with a card's points.--canvas-label-editor-inline-sizeHow wide the field a label is edited in is.--viewport-control-background-colorThe ground under the pan and zoom buttons, one name with `Map`.
Custom stateDescriptionconnectingWhile a reader is drawing a connection.directWhile the board moves without easing: under the reader's hand, or settling into its box.emptyWhile the document has no nodes.fullscreenWhile the board fills the screen.holdingWhile something a click picked up follows the pointer, until the next press puts it down.idleWhile the reader has been still long enough to hide the chrome.pressingWhile a press on the board, its cards or its connections is under way.settledSet a frame after the first render. Transitions are held off until it is, so an element never animates its own arrival.
Edgehelix-canvas-edgeA connector between two cards on a canvas.
PropTypeDefaultDescriptionfromstring""The card it leaves.fromEnd"none"|"arrow"What sits at the end it leaves from.fromSide"top"|"right"|"bottom"|"left"Which side of that card it leaves, where the document says.labelstringWhat the connector says, drawn at its middle.namestring""What a request calls this connection, unique on its board.path"straight"|"step"How it travels: `straight`, or `step` for right angles.readOnlybooleanfalseKeeps this connection: a reader cannot remove it.tostring""The card it arrives at.toEnd"none"|"arrow"What sits at the end it arrives at. Absent is an arrow, as the format says.tone"accent"|"danger"|"info"|"neutral"|"primary"|"success"|"warning"What the connection means, in the words every Helix component uses.toSide"top"|"right"|"bottom"|"left"Which side of that card it arrives at, where the document says.variant"dashed"|"dotted"How the line is drawn: `dashed` or `dotted`, and solid where it says
neither.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
Custom stateDescriptionsettledSet a frame after the first render. Transitions are held off until it is, so an element never animates its own arrival.
Nodehelix-canvas-nodeOne card or group on a canvas.
PropTypeDefaultDescriptiongroupbooleanfalseA box drawn behind the cards inside it rather than a card.heightnumber0How tall the card is, in the document's own units.labelstring""What the card is called, for a group and wherever another card names it.material"frosted"|"glass"|"transparent"What the card's ground is made of: `glass` or `frosted`, which let the
board's ruling show through, or `transparent`.namestring""What connections and requests call this card, unique on its board.readOnlybooleanfalseKeeps this card where it is: not moved, not connected, not removed.separation"elevated"|"filled"|"outlined"|"plain"How the card stands off the board.shape"circle"|"diamond"|"pill"|"square"The card's outline: `circle`, `diamond`, `pill` or `square`, and a rounded
box where it says none.tone"accent"|"danger"|"info"|"neutral"|"primary"|"success"|"warning"What the card means, in the words every Helix component uses for it.widthnumber0How wide the card is, in the document's own units.xnumber0Where its left edge sits, in the document's own units.ynumber0Where its top edge sits, in the document's own units.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)What the card holds, which is anything: text, a picture, a chart.descriptionA quieter line under it.
MethodTypeDescriptionfocus(options: FocusOptions) => voidFocuses the card rather than the host, which draws no box of its own.
PartDescriptiongripA corner a selected card is resized from, on every one of the four.grip-bottom-leftThe bottom left corner.grip-bottom-rightThe bottom right corner.grip-top-leftThe top left corner.grip-top-rightThe top right corner.handleA point on a side a connection is drawn from, on every one of the four.handle-bottomThe point on the bottom side.handle-leftThe point on the left side.handle-rightThe point on the right side.handle-topThe point on the top side.moveThe handle a selected card is moved by, a click to pick it up and another to put it down, as well as a drag.nodeThe box the content sits in.outlineThe drawn outline of a card whose shape a box cannot draw, a diamond.
CSS PropertyDescription--canvas-grip-sizeHow large the corners a selected card is resized from are.--canvas-handle-sizeHow large the points a connection is drawn from are.--canvas-move-block-sizeHow tall the grip a selected card is moved by is.--canvas-move-inline-sizeHow wide the grip a selected card is moved by is.--canvas-move-insetHow far in from the card's corner that grip sits.--canvas-node-background-colorThe ground the card is drawn on.--canvas-node-colorA color with no meaning, where a tone will not do: a hex a document chose.--canvas-node-paddingSpace between the card's edge and what it holds.--canvas-node-shadowThe lift under the card, which `separation="elevated"` sets.
Custom stateDescriptioncandidateWhile a connection is being drawn and this card is somewhere it could arrive.currentWhile this is the card a reader lands on when they tab into the board.selectedWhile this is the card the reader selected, until they select something else or nothing.settledSet a frame after the first render. Transitions are held off until it is, so an element never animates its own arrival.targetWhile a connection being drawn would arrive here if it were let go.
Roothelix-headless-canvasA board of cards and the connections between them, which a reader can walk, rearrange and connect.
PropTypeDefaultDescriptioncomesFromLabelstring"from {cards}"How a card says where its connections come from, with `{cards}`.connectedLabelstring"Asked to connect {from} to {to}."What it says when a connection is asked for, with `{from}` and `{to}`.connectingLabelstring"Connecting from {from}. Move to another card and press Enter, or Escape to stop."What the live region says when a reader starts a connection, with `{from}`
filled in.connectionLabelstring"From {from} to {to}"What a connection is called, with `{from}` and `{to}`.controlsstringWhich of the controls this surface draws, as a list of what to keep.controlsLabelstringWhat the group of controls is called, for a reader who meets it.controlsPlacement"top-start"|"top-end"|"bottom-start"|"bottom-end"Which corner the controls sit in.fullscreenLabelstring"Fill the screen"What the control that fills the screen is called.idleDelaynumber0How long the reader may be still before the chrome hides, in milliseconds.labelstring""Accessible name for the board, which is the one thing a consumer must write.labelEditorLabelstring"Label for {name}"What the field a label is edited in is called, with `{name}` for what it
labels.leadsToLabelstring"leads to {cards}"How a card says where its connections go, with `{cards}` as the list.order"spatial"|"edges"The order a reader meets the cards in.panDownLabelstring"Pan down"What the control that pans down is called.panLeftLabelstring"Pan left"What the control that pans left is called, on screen.panRightLabelstring"Pan right"What the control that pans right is called, on screen.panStepnumber0.25How far one press moves the view, as a fraction of what is on screen.panUpLabelstring"Pan up"What the control that pans up is called.path"straight"|"step"How every connection travels, where it does not say: `straight`, or `step`
for right angles.readOnlybooleanfalseKeeps every card where its author put it.reconnectingLabelstring"Moving the end of the connection from {from} to {to}. Move to a card and press Enter, or Escape to stop."What the live region says when a reader picks up a connection's end, with
`{from}` and `{to}`.selectedstring""The cards and connections the reader selected, by name, comma separated,
and empty for none.stoppedLabelstring"Stopped connecting."What it says when a reader stops connecting without asking.viewCanvasViewWhere the board is looking: the document's point at the middle of the view,
and the zoom.zoomInLabelstring"Zoom in"What the control that zooms in is called.zoomOutLabelstring"Zoom out"What the control that zooms out is called.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescriptionemptyWhat to show where the document has no nodes.footerChrome below the board.headerChrome above the board.
EventTypeDescriptionhelix-before-moveHelixBeforeMoveEventCards are about to move. Refuse it to keep the positions in your own state.helix-before-reconnectHelixBeforeReconnectEventA connection's end is about to move to another card or side. Refuse it to keep connections in your own state.helix-before-relabelHelixBeforeRelabelEventA connection's label or a group's name is about to change. Refuse it to keep labels in your own state.helix-canvas-editHelixCanvasEditEventThe reader asked to edit a card: a double-click, or Enter or F2. Open your own editor for it.helix-canvas-panHelixCanvasPanEventThe board was moved a step, by its controls or the arrow keys: a fact rather than a request. A drag says so through `helix-canvas-view`.helix-canvas-viewHelixCanvasViewEventWhere the board is looking changed, however it changed. The detail is the new view.helix-canvas-zoomHelixCanvasZoomEventThe board zoomed a step, by its controls or the keys. A wheel or a pinch says so through `helix-canvas-view`.helix-connectHelixConnectEventA reader asked for two cards to be joined. Add the `helix-canvas-edge` to do it.helix-moveHelixMoveEventCards moved and the move is finished: a drag let go, a click that put a card down, or a key pressed.helix-reconnectHelixReconnectEventA connection's end moved, and the move is finished.helix-relabelHelixRelabelEventA connection's label or a group's name changed.helix-removeHelixRemoveEventA reader asked for cards or connections to go. Remove the elements it names.helix-selectHelixSelectEventThe selection changed. The detail's `value` is the names, comma separated, empty for none. Cancelable: refusing it keeps the selection where it was.
MethodTypeDescriptionfit() => voidFits the whole board into the box, centered, and never magnified past its
own size.pan(to: ViewportWay) => voidMoves the board, and says so.show(name: string) => voidBrings a card, by name, to the middle of the viewport.toggleFullscreen() => voidFills the screen with the surface, or comes back.toJsonCanvas() => CanvasDocumentThe board as a JSON Canvas document, for saving it.zoom(by: number) => voidZooms the board about the middle of the view, and says so.
PartDescriptionarrowThe head an edge carries at an end that has one.boardThe plane the cards are placed on, which is what pans and zooms.controlsThe group the pan and zoom buttons sit in.draftThe connection being drawn, before it is asked for.edgeOne connector between two cards.edge-endAn end of a selected connection, which a press picks up, a click as well as a drag.edge-targetThe wider, unpainted line over a connector that a reader focuses and presses.edgesThe layer the connectors are drawn in.footerThe strip below the board.fullscreenThe button that fills the screen.headerThe strip above the board.labelThe label on a connector.label-editorThe field a connection's label or a group's name is edited in, where it sits.liveWhat the board says while a connection is being made, for a screen reader.marqueeThe box a Shift-drag across the empty board draws, which selects the cards it touches.pan-downThe button that moves the board down.pan-endThe button that moves the board the way the text ends.pan-startThe button that moves the board the way the text starts.pan-upThe button that moves the board up.regionThe named region the board is drawn in.viewportThe box the board is drawn inside.zoom-inThe button that zooms in.zoom-outThe button that zooms out.
Custom stateDescriptionconnectingWhile a reader is drawing a connection.directWhile the board moves without easing: under the reader's hand, or settling into its box.emptyWhile the document has no nodes.fullscreenWhile the board fills the screen.holdingWhile something a click picked up follows the pointer, until the next press puts it down.idleWhile the reader has been still long enough to hide the chrome.pressingWhile a press on the board, its cards or its connections is under way.settledSet a frame after the first render. Transitions are held off until it is, so an element never animates its own arrival.
Edgehelix-headless-canvas-edgeA connector between two cards on a canvas.
PropTypeDefaultDescriptionfromstring""The card it leaves.fromEnd"none"|"arrow"What sits at the end it leaves from.fromSide"top"|"right"|"bottom"|"left"Which side of that card it leaves, where the document says.labelstringWhat the connector says, drawn at its middle.namestring""What a request calls this connection, unique on its board.path"straight"|"step"How it travels: `straight`, or `step` for right angles.readOnlybooleanfalseKeeps this connection: a reader cannot remove it.tostring""The card it arrives at.toEnd"none"|"arrow"What sits at the end it arrives at. Absent is an arrow, as the format says.tone"accent"|"danger"|"info"|"neutral"|"primary"|"success"|"warning"What the connection means, in the words every Helix component uses.toSide"top"|"right"|"bottom"|"left"Which side of that card it arrives at, where the document says.variant"dashed"|"dotted"How the line is drawn: `dashed` or `dotted`, and solid where it says
neither.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
Custom stateDescriptionsettledSet a frame after the first render. Transitions are held off until it is, so an element never animates its own arrival.
Nodehelix-headless-canvas-nodeOne card or group on a canvas.
PropTypeDefaultDescriptiongroupbooleanfalseA box drawn behind the cards inside it rather than a card.heightnumber0How tall the card is, in the document's own units.labelstring""What the card is called, for a group and wherever another card names it.namestring""What connections and requests call this card, unique on its board.readOnlybooleanfalseKeeps this card where it is: not moved, not connected, not removed.shape"circle"|"diamond"|"pill"|"square"The card's outline: `circle`, `diamond`, `pill` or `square`, and a rounded
box where it says none.tone"accent"|"danger"|"info"|"neutral"|"primary"|"success"|"warning"What the card means, in the words every Helix component uses for it.widthnumber0How wide the card is, in the document's own units.xnumber0Where its left edge sits, in the document's own units.ynumber0Where its top edge sits, in the document's own units.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)What the card holds, which is anything: text, a picture, a chart.descriptionA quieter line under it.
MethodTypeDescriptionfocus(options: FocusOptions) => voidFocuses the card rather than the host, which draws no box of its own.
PartDescriptiongripA corner a selected card is resized from, on every one of the four.grip-bottom-leftThe bottom left corner.grip-bottom-rightThe bottom right corner.grip-top-leftThe top left corner.grip-top-rightThe top right corner.handleA point on a side a connection is drawn from, on every one of the four.handle-bottomThe point on the bottom side.handle-leftThe point on the left side.handle-rightThe point on the right side.handle-topThe point on the top side.moveThe handle a selected card is moved by, a click to pick it up and another to put it down, as well as a drag.nodeThe box the content sits in.outlineThe drawn outline of a card whose shape a box cannot draw, a diamond.
Custom stateDescriptioncandidateWhile a connection is being drawn and this card is somewhere it could arrive.currentWhile this is the card a reader lands on when they tab into the board.selectedWhile this is the card the reader selected, until they select something else or nothing.settledSet a frame after the first render. Transitions are held off until it is, so an element never animates its own arrival.targetWhile a connection being drawn would arrive here if it were let go.
ExamplesNameDescriptionBoardA board written as markup, drawn where its author placed each card, with a reading order for anyone who cannot see the placement.ControlledA board whose page holds the positions: it refuses each move and places the card itself, here on the ruling.EditingA board a reader rearranges: draw from a card's edge to another to join them, drag a connection's end to move it, double-click to edit, and Delete takes a card or a connection away.FlowchartA flowchart: a pill to start and end, boxes for steps, a diamond for the decision, joined at right angles.PreviewA board of cards and the arrows between them, drawn where its author placed each one.PreviewA board of cards and the arrows between them, drawn where its author placed each one.PublishedA board that is published rather than worked on: every card stays where its author put it, and every connection turns in right angles.RichCards holding a consumer's own components, which is what a board made of elements is for.StylesHow cards stand off the board and how connections are drawn: outlined, filled, elevated and plain cards, and solid, dashed and dotted lines.