Getting Started

Introduction

KronoGraph is a JavaScript library for building time-based visualizations.

To see how KronoGraph works with KeyLines and ReGraph, explore the Integration Playground.

If you need help with converting your data into the correct KronoGraph format, see the Handling Data section.

If you would like an introduction to the basic principles of building a timeline and getting up-and-running with KronoGraph, follow this guide. We are going to embed a simple timeline in an HTML pagea React application, before adding data and attaching an event handler.

For the ReactJavaScript version of this guide, use the toggle in the top left corner.

Creating & Serving an App

First we need to create an app to add a Timeline component to. If you don't have an existing project, you can easily create one with Vite using your preferred package.

npm create vite@latest my-kronograph-app -- --template vanilla
yarn create vite my-kronograph-app --template vanilla
pnpm create vite my-kronograph-app --template vanilla
npm create vite@latest my-kronograph-app -- --template react
yarn create vite my-kronograph-app --template react
pnpm create vite my-kronograph-app --template react

Once this process has completed, you can start your app:

cd my-kronograph-app
npm install
npm run dev
cd my-kronograph-app
yarn install
yarn dev
cd my-kronograph-app
pnpm install
pnpm run dev

By default, Vite runs a development server at http://localhost:5173.

Installing

Now that you have an app, download the latest version of KronoGraph:

Download KronoGraph

For Safari browsers, hold the ⌥ Option key when pressing the Download button to download the correct .tgz format.

Open a new terminal window and access your project's root folder, which contains the app you just created:

cd my-kronograph-app

Next move the download into this folder. Do not change the file name. If you are on a UNIX-like operating system you can move the download from the terminal:

mv ~/Downloads/your_downloaded_file_name.tgz .

From your project's root folder, install the bundle as a local package:

npm install file:your_downloaded_file_name.tgz
yarn add kronograph@file:./your_downloaded_file_name.tgz
pnpm add file:your_downloaded_file_name.tgz

Creating a Timeline

It's time to add a timeline to the app.

First we need to add an element to the HTML page so that KronoGraph can attach a Timeline to it. We then call createTimeline(), passing the id of the parent element to it.

Let's load the files into the page and create a div for the Timeline. Add the following to index.html:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Hello, world!</title>
    <link rel="stylesheet" href="/src/style.css" />
    <script type="module" src="/src/main.js"></script>
    <!--if you are using TypeScript, delete the line above and then uncomment the line below-->
    <!--<script type="module" src="main.ts"></script>-->
  </head>
  <body>
    <div id="my-timeline" class="timeline"></div>
  </body>
</html>

Next we import createTimeline into the page, create a Timeline element in main.js, and add some data:

// main.js

import { createTimeline } from 'kronograph';

const timeline = createTimeline('my-timeline');

const data = {
  entities: { 'Person 1': {}, 'Person 2': {} },
  events: {
    'Phone call 1': {
      entityIds: ['Person 1', 'Person 2'],
      time: new Date(2020, 6, 1, 12, 0),
    },
    'Phone call 2': {
      entityIds: ['Person 1', 'Person 2'],
      time: new Date(2020, 6, 1, 13, 0),
    },
    'Phone call 3': {
      entityIds: ['Person 2', 'Person 1'],
      time: new Date(2020, 6, 1, 14, 0),
    },
  },
};

timeline.set(data);
timeline.fit();

And define some styling in style.css:

/* style.css */
.timeline {
  height: 100vh;
  width: 100vw;
}

body {
  margin: 0;
}

This guide assumes that your component is declared in App.jsx. You can also use a separate file but you will need to make sure your architecture includes it in the app.

To create a timeline, we need to import the Timeline component into the app and then pass some data into the Timeline component's props. Replace the contents of App.jsx with:

// App.jsx
import React from 'react';
import Timeline from 'kronograph/react/Timeline';

const data = {
  entities: { 'Person 1': {} , 'Person 2': {} },
  events: {
    'Phone call 1': {
      entityIds: ['Person 1', 'Person 2'],
      time: new Date(2020, 6, 1, 12, 0),
    },
    'Phone call 2': {
      entityIds: ['Person 1', 'Person 2'],
      time: new Date(2020, 6, 1, 13, 0),
    },
    'Phone call 3': {
      entityIds: ['Person 2', 'Person 1'],
      time: new Date(2020, 6, 1, 14, 0),
    },
  },
};

function App() {
  return (
    <div style={{ height: '100vh', width: '100vw' }}>
      <Timeline entities={data.entities} events={data.events} />
    </div>
  );
}

export default App;

The timeline sets its height and width to equal the size of its parent element, so any styles should be set on the parent.

Your timeline should now look like this:

Adding Timeline

Log in to view live examples

Handling Interactions

KronoGraph has a few useful default functions to let users navigate the timeline. You can add your own custom behavior to user interactions by attaching a custom handler:

To define a custom handler, add a new handler function after your data in main.js:

// main.js
function clickHandler(event) {
  window.alert(`You clicked a timeline item of type '${event.targetType}'`);
}

And then attach it to the Timeline by adding this after createTimeline():

// main.js
timeline.on('click', clickHandler);

To define a custom handler, add a new handler to the App() function in App.jsx:

// App.jsx
const clickHandler = event => {
  window.alert(`You clicked a timeline item of type '${event.targetType}'`);
}

And now pass it to the onClick prop:

// App.jsx
<Timeline
  entities={data.entities}
  events={data.events}
  onTimelineClick={clickHandler}
/>

Your app should now look like the one below. Try clicking on entities and events on the timeline to see their type in a browser alert.

Events

Log in to view live examples

Congratulations! You have created your first KronoGraph app. Here are some ideas what to do next:

MCP Servers

Model Context Protocol (MCP) is an open-source standard to expose tools, data, or functionality to AI applications.

KronoGraph MCP server enables AI agents in your code editor to access our APIs and docs and provides more accurate and relevant help when developing with KronoGraph.

All Cambridge Intelligence products have MCP servers. You can use them individually or together when integrating multiple products from our suite.

MCP servers are compatible with different code editors thanks to the universal open-source standard. Generally, code editors have an MCP configuration file, often named mcp.json. Every MCP server is added to this config file as a new entry:

{
  "servers": {
    "kronograph": {   // our KronoGraph MCP server
      "url": "https://mcp.cambridge-intelligence.com/kronograph",
      "type": "http"
    },
    "mapweave": {   // our MapWeave MCP server
      "url": "https://mcp.cambridge-intelligence.com/mapweave",
      "type": "http"
    },
    / ... /
  }
}

This section shows how to add MCP servers to selected code editors. If your code editor isn't here, check the official documentation for the exact location of the MCP config file.

Claude Code

First, install Claude Code globally in your environment:

npm install -g @anthropic-ai/claude-code

Next, add a new MCP server to Claude and name it:

claude mcp add --transport http my-kronograph-mcp-server https://mcp.cambridge-intelligence.com/kronograph

Finally, verify that the server is running:

claude mcp list

For details and troubleshooting, see Connect Claude Code to tools via MCP.

Cursor

Create a config file .cursor/mcp.json in your project's root folder and add the MCP server:

{
  "mcpServers": {
    "kronograph": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://mcp.cambridge-intelligence.com/kronograph"]
    }
  }
}
  • "npx": Runs the server using npx tool by Node.js
  • "-y": Confirms the installation
  • "mcp-remote@latest", "https://mcp.cambridge-intelligence.com/kronograph": Downloads the package

This method downloads the MCP server as a package using mcp-remote because Cursor currently doesn't consistently support streamable http connections.

To verify the server is running, press Shift+Command+U (Mac) / Ctrl+Shift+U (Win) to open the Output panel. Select MCP Logs from the drop-down menu to view logs confirming that the server is connected.

For details and troubleshooting, see the Model Context Protocol (MCP) docs by Cursor.

JetBrains IDEs

To add an MCP server to JetBrains IDEs such as IntelliJ IDEA or WebStorm, use the latest version of the IDE and install the JetBrains AI Assistant plugin.

  1. Go to Settings | Tools | AI Assistant | Model Context Protocol (MCP).
  2. Click the + button to add a new MCP server.
  3. Select As JSON in the top left corner of the edit window.
  4. Add the new server in the edit window:
{
  "mcpServers": {
    "kronograph": {
      "url": "https://mcp.cambridge-intelligence.com/kronograph",
      "type": "http"
    }
  }
}

To verify the server is running, go to Help | Show Log in Explorer/Finder/Nautilus (depending on OS). The directory contains an mcp folder with a separate log file for each added MCP server.

For details and troubleshooting, see the Model Context Protocol (MCP) docs by JetBrains.

VS Code

Make sure you are on the latest version of VS Code and have access to GitHub Copilot.

  1. Press Shift+Command+P (Mac) / Ctrl+Shift+P (Win) to open the Command Palette.
  2. Locate the MCP: Add Server command in the search bar and select it.
  3. Select the HTTP (HTTP or Server-Sent Events) option.
  4. Paste in the server URL and press Enter to confirm:
https://mcp.cambridge-intelligence.com/kronograph
  1. Create a unique server ID and press Enter to confirm:
my-kronograph-mcp-server
  1. Select the scope of work for this MCP server. The options are:
  • Workspace: Available in this workspace and runs locally, recommended by us
  • Global: Available in all workspaces and runs globally

This creates an mcp.json file in the .vscode directory with the MCP server specified.

To verify the server is running, click the Extensions icon in the left navigation panel and find the MCP SERVERS - INSTALLED tab. Right-click on the server listed in this tab and select Show Output to view logs confirming that the server is connected.

For details and troubleshooting, see the Use MCP servers in VS Code docs by VS Code.

Example prompts

To help you get started, here are some example prompts to use for the MCP servers:

  • Create a new KronoGraph project using pnpm as a package manager and Vite as a bundler that shows a simple timeline with two entities connected by an event.
  • Add a ReGraph chart into my KronoGraph project and visualize my entities as a chart.
  • How to add more entities to an existing timeline in KronoGraph?
  • What is the difference between an event and an event fold?
  • How can I style my annotations to make them look better?

Data we collect

We collect a short list of key words from your prompts and the answers provided by the MCP server, and we analyze this data so we can continue improving our MCP server for a better developer experience. The format may look like this:

"query": "export timeline to PNG image"

Terms of use

These terms do not alter or supersede any existing agreements between you (or your employer) and us.

By accessing or using any Content you agree to be bound by these Terms of Use. Please review these terms carefully before using the website.

The contents of this website, including but not limited to any text, code samples, API references, schemas, interactive tools, and other materials (collectively, the 'Content'), are made available for informational and internal evaluation purposes only. All intellectual property rights in the Content are reserved. No licence is granted to use the Content for any commercial purpose, or to copy, distribute, modify, reverse-engineer, or incorporate any part of the Content into any product or service, without our prior written consent.

This Content is provided “as is” and “as available,” without any representations, warranties, or guarantees of any kind, whether express or implied, including but not limited to implied warranties of merchantability, fitness for a particular purpose, non-infringement, or accuracy. To the fullest extent permitted by applicable law, we expressly exclude and disclaim all implied warranties, conditions, and other terms that might otherwise be implied.

We disclaim all liability for any loss or damage, whether direct, indirect, incidental, consequential, or otherwise, arising from any reliance placed on the Content or from your use of it, to the fullest extent permitted by applicable law. By continuing to access or use the Content, you acknowledge and agree to these terms.