Typescript

JointJS provides full Typescript support for your applications. Types are part of the @joint/core and @joint/plus packages and can be used ouf of the box.

Quickstart example

Here is the example of a quickstart application written using Typescript:

Open Sandbox

As you can see, this example is almost the same as the Javascript one. The only difference is several type specifications in custom functions. All the types are imported from the @joint/core and @joint/plus packages and are ready to use.

Custom shape Typescript declaration

You can leverage Typescript if using it when creating custom shapes. All models in JointJS are generic types with the model attribute interface as a type parameter. Here is the declaration of dia.Cell class in Typescript:

class Cell<A extends ObjectHash = Cell.Attributes, S extends mvc.ModelSetOptions = dia.ModelSetOptions> extends mvc.Model<A, S> {
    // ...
}

You can see that the Cell class is a generic class with two type parameters. The first one is the attributes interface, and the second one is the set options interface. The first type parameter is used to specify the model attributes of the model. This type is used in the constructor, and the get and set methods of the model. The second type parameter is used to specify the options that can be passed to the set method of the model. Most of the time you don't need to specify the second type parameter, as its default value fits most custom shapes.

// Type 'A' is declared in the class declaration
constructor(attributes?: DeepPartial<A>, opt?: Cell.ConstructorOptions);

// Set method signature as it would be used in the Cell class
set(attributeName: Partial<A>, options?: S): this;

Let's declare a custom element with Typescript. The custom element will have an additional attribute enabled that is not present in the default dia.Element.Attributes interface. Other parts of declaration remain the same when using Typescript. You can learn more about custom shapes in the custom shapes section.

interface CustomElementAttributes extends dia.Element.Attributes {
    enabled?: boolean;
}

class CustomElement extends dia.Element<CustomElementAttributes> {
    // ...
}

Here is the example of a custom shape declaration in Typescript:

Open Sandbox

Frequently asked questions

What should I do if I encounter an incorrect TypeScript declaration?

Occasionally, you may encounter an incorrect TypeScript declaration inside JointJS library code. You should report such errors to us, and in the meantime instruct TypeScript not to enforce the offending declaration.

Learn more...

We treat the JointJS documentation as the source of truth for any public function. If there is a mismatch between a TypeScript declaration and the documented behavior of a function, you should trust the documentation and tell us about the mismatch in types via any support channel available to you (email, ticketing system, GitHub Discussions, ...).

While we work on fixing your reported issue, you can work around the incorrect type checking by instructing TypeScript to ignore any errors on the next line via the // @ts-ignore comment.

For example, we previously had an error where the TypeScript declaration of paperScroller.transitionToPoint() was missing the two-argument signature, despite it being valid according to the function's documentation. This caused an Argument of type '{ x: number; y: number; }' is not assignable to parameter of type 'number'. (ts2435) error to be thrown when one of our customers tried to use the two-argument signature:

paperScroller.transitionToPoint({ x: 100, y: 100 }, { duration: '500ms' });

We advised the customer who noticed the issue to temporarily instruct TypeScript to ignore the error until we could release a patch to properly fix the JointJS type declaration:

// @ts-ignore
paperScroller.transitionToPoint({ x: 100, y: 100 }, { duration: '500ms' });

How can I embed the code from a JointJS example application into my own application?

In the simplest case, it is enough to build the example application, copy-paste the build file into your application, and add two HTML elements to your HTML (one <div> to act as a holder for the JointJS paper, and one <script> to load the build file).

Learn more...

tip

If your web app is written in a JavaScript framework, you should start by reading its dedicated tutorial page.

info

This answer uses the Database application as an example, but the steps would be almost identical for any other JointJS example application.

Let's say that the Database application nicely fits the requirements of your project and you want to use it as the base on top of which you will build your app's functionality. How would you do that?

• You can find the Database source code in the folder jointplus/apps/Database, where jointplus is the folder which gets created when you unzip your JointJS+ package. The folder location is the same in the paid package (downloaded from my.jointjs.com) and in the trial package. In the folder, you have two options:
  • If your web app is using TypeScript, you should go into the ts folder.
  • If your web app is using JavaScript, then you should go to the es6 folder.
• In either folder, you can find a README.md file with instructions - you need to run npm install and npm start from your command line (called Terminal on Mac OS).
  • To have access to these commands, you need to have Node.js installed on your computer (https://nodejs.org/en).
• You can then see the demo in action by opening the localhost page mentioned in the command line (typically localhost:8080).
  • Importantly, this also builds a dist/bundle.js file via Webpack, which contains all JointJS+ dependencies of the Database application.
• To see what embedding JointJS into a web app looks like, open the dist/index.html file. You will see that its structure is very simple - inside the <body> tag, it specifies:
  • A <div> element to serve as the Paper of the JointJS diagram.
  • A reference to JointJS dependencies via a <script> tag (in our example, this is the file built by Webpack, so <script src="bundle.js"></script>).
• The source code of the Database app can be found inside the src folder (referenced from the index.js file).
  • Notice that the #canvas HTMLElement is referenced in src/app.js (as canvasEl variable), and used as the base of a PaperScroller object which extends a Paper object. This is the magic which connects JointJS to the HTML.

All that is to say, if you want to have the Database app inside your web app right now, all you have to do is to add a <div id="canvas"> HTML element and a <script> HTML element pointing to bundle.js file built by npm (and copy-paste the bundle.js file somewhere where your web app can find it), and you are good to go.