Get started with GoJS

This page covers the basics of GoJS, including installation, a minimal working diagram, templates, models, and bindings.

You can link straight to a GoJS library provided by a CDN such as:

go is the JavaScript namespace in which all GoJS types reside. In this documentation all code uses of GoJS classes such as Diagram or Node or Panel or Shape or TextBlock will be prefixed with go..

If you are using a package manager such as npm you can install the "gojs" package:

See detailed installation options here.

The hosting <div>

You'll also need a <div> with an explicit size to host the diagram. You can style the div, but not anything that GoJS inserts into the div.

In JavaScript code you pass the <div>'s id when making a Diagram, or else a reference to the <div> element:

A minimal diagram

Here's a small GoJS Diagram. Four nodes and four links, undo/redo enabled.

Four major concepts:

• A Diagram can be thought of as a view of a Model.
• Models hold the data that describe the nodes and links. Models, not Diagrams, are what you load and then save after editing.
• Templates (Diagram.nodeTemplate, Diagram.linkTemplate) describe how to render each Node or Link from a data object.
• Bindings (GraphObject.bind) connect template properties to data fields in the model.

You'll also notice above that some interaction is already possible:

• Click and drag the background in the above diagram to pan the view.
• Click a node to select it, or click and drag to move it around.
• To create a selection box, click and hold on the background, then start dragging.
• Use Ctrl + C and Ctrl + V, or control-drag-and-drop, to make a copy of the selection. (On a Mac, use ⌘ as the modifier for all commands, but you must use Alt as the modifier for a copying drag-and-drop.)
• Press Delete to delete selected nodes. (Read about Keyboard Commands.)
• On touch devices, press and hold to bring up a context menu. (Read about Context Menus.)
• Since the undo manager was enabled, Ctrl + Z and Ctrl + Y (or Ctrl + Shift + Z) will undo and redo moves and copies and deletions.

Building Parts

A Part (Node, Link, Group) is a tree of visual GraphObjects, mostly Shapes, TextBlocks, Pictures, and nested Panels. Construct each object with new, set properties via the constructor argument, and add elements to Panels with Panel.add. GraphObject methods return this, so chaining works.

Panel types control how Panel elements (children) are laid out. The most common:

• 'Auto' or go.PanelTypes.Auto — the first element surrounds all the others (e.g. shape wraps a text block).
• 'Vertical' or go.PanelTypes.Vertical — stack elements top-to-bottom.
• 'Horizontal' or go.PanelTypes.Horizontal — stack elements left-to-right.
• 'Spot' or go.PanelTypes.Spot — position elements at named spots (e.g. go.Spot.Center, go.Spot.TopRight) around the main (first) element.
• 'Table' or go.PanelTypes.Table — grid of rows and columns.

Most of our code uses a quoted string, but the go.PanelTypes constant enumerates all possibilities, and may be easier to use with auto-completion.

See Panels for the full list, and many Panel examples.

Models and data

GoJS has three built-in model types. Choose the type of model based on the relationships in your data:

• GraphLinksModel — Arbitrary graphs with independent link data. Also allows Groups. Use this unless you have a reason not to.
• TreeModel — Each node data has a parent reference; no separate link data array. Good for org charts and other pure trees.
• Model — If you don't need Links or Groups and you have a lot of parts, you can use simple Parts instead of Nodes for efficiency.

In TypeScript, models are generic so you can have optional type safety on node/link data:

See Using Models for more discussion.

Data bindings

A binding connects a property of a GraphObject in the template to a property of the data object in the model. Three forms, from most to least common:

Use a conversion function when the source property value type doesn't match the target property type:

See Data Binding for full details including converter signatures and two-way back-converters.

Link templates

Links follow the same template pattern as nodes, but a Link has a special panel type that normally contains a path Shape and optional arrowheads and labels.

The curve: go.Curve.Bezier Link option gives the Link a Bezier arc path.

See many more Link options on the Links page.

Interaction and commands

A diagram has a CommandHandler (for standard commands like copy, delete, undo, redo) and a ToolManager (for mouse- and touch-driven interaction). You infrequently construct these for each Diagram; normally you just set their properties.

For more on the built-in possibilities, see the Interactivity and Commands pages.

Layouts

In many diagrams the user can position nodes manually by moving them. A Layout positions nodes automatically according to some algorithm. Common choices:

Automatic layouts occur after nodes or links are added or removed or they change visibility or after nodes change size.

If you do not set Diagram.layout, each node must be given a location, either manually via the user's dragging, or via data binding.

For more on how layouts can work, see the Layouts page.

Routing

Each Link has a built-in efficient behavior that controls the path that it takes, depending on the link's properties, as you have seen above with the Link.curve property.

More generally, the routes of links can also be determined by a Router, allowing the consideration of other nodes or links besides the two nodes connected by the link. In the following example, the AvoidsNodes router is used to plot a path that avoids crossing over nodes. The functionality is enabled by setting Link.routing in the link template: routing: go.Routing.AvoidsNodes.

Try dragging the "Beta" node around. The link will automatically try to re-route around Nodes to avoid crossing them, except when it is unavoidable.

For more on how routers can work, see the Routers page.

Common issues

• The host <div> must have an explicit width and height (CSS units). A zero width or height div renders a blank diagram.
• You do not commonly construct Node or Link instances and add them to a diagram directly. Instead, add data to the model, and GoJS constructs Parts from your data, based on your templates.
• To modify the model after the diagram exists, you must call Model.set or another Model method with the Node data, in a transaction. Modifying node data in the nodeDataArray directly will not update the diagram.
• Property names in templates are the target; property names in data are the source. .bind("visible", "vis") means automatically set the GraphObject.visible property from the data.vis property.

Where to go next

• Building GraphObjects — detail on panels, shapes, text.
• Using Models and Templates — model types and node/link data conventions.
• Data Binding — one-way, two-way, converters, model bindings.
• Samples — 200+ examples across every major feature.
• API Reference — the full type-accurate documentation.

You may want to read more tutorials, such as the GraphObject Manipulation tutorial and the Interactivity tutorial.

If you want to explore by example, have a look at the samples to get a feel for what's possible with GoJS.