Search

HTMLOverlays

Interactions

Position HTML elements over entity and event locations.

HTMLOverlays
View live example →

Pan and zoom the timeline to see how the HTML overlays move with the events and entities.

Use the entity and event locations to position HTML elements over the timeline.

See Also

Pan and zoom the timeline to see how the HTML overlays move with the events and entities.

Use the entity and event locations to position HTML elements over the timeline.

See Also

import { createTimeline } from "kronograph";
import data from "./data";

const smallPadding = 6;
const bigPadding = 12;
const entityBox = document.getElementById("entity-box");
const entityLabel = document.getElementById("entity-label");
const eventBox = document.getElementById("event-box");
const eventLabel = document.getElementById("event-label");
const timeline = createTimeline("my-timeline");
timeline.set(data);
timeline.fit();

function annotateEntity() {
  const position = timeline.getEntityPosition("west-josephine-126");
  if (position === null) {
    entityBox.style.display = "none";
    entityLabel.style.display = "none";
  } else {
    entityBox.style.display = "block";
    entityLabel.style.display = "block";

    // position box
    let { x1, x2, y1, y2 } = position;
    y1 -= smallPadding;
    y2 += smallPadding;
    entityBox.style.left = `${x1}px`;
    entityBox.style.width = `${x2 - x1}px`;
    entityBox.style.top = `${y1}px`;
    entityBox.style.height = `${y2 - y1}px`;

    // position label
    const entityCenterX = (x1 + x2) / 2;
    entityLabel.style.left = `${entityCenterX - entityLabel.offsetWidth / 2}px`;
    entityLabel.style.top = `${y2 + smallPadding}px`;
  }
}

function annotateEvent() {
  const position = timeline.getEventPosition("Email 5");
  if (position === null) {
    eventBox.style.display = "none";
    eventLabel.style.display = "none";
  } else {
    eventBox.style.display = "block";
    eventLabel.style.display = "block";

    // position box
    let { x1, x2, y1, y2 } = position;
    x1 -= bigPadding;
    x2 += bigPadding;
    y1 -= bigPadding;
    y2 += bigPadding;
    eventBox.style.left = `${x1}px`;
    eventBox.style.width = `${x2 - x1}px`;
    eventBox.style.top = `${y1}px`;
    eventBox.style.height = `${y2 - y1}px`;

    // position label
    eventLabel.style.left = `${x2 + smallPadding}px`;
    eventLabel.style.top = `${y1 - smallPadding - eventLabel.offsetHeight}px`;
  }
}

timeline.on("draw", () => {
  annotateEntity();
  annotateEvent();
});
export default {
  entities: {
    "smith-johnathan-151": {
      label: "John Smith",
    },
    "west-josephine-126": {
      label: "Josephine West",
    },
    "roberts-nathaniel-023": {
      label: "Nathan Roberts",
    },
    "baxter-eleanor-004": {
      label: "Ella Baxter",
    },
  },
  events: {
    "Email 1": {
      entityIds: ["smith-johnathan-151", "roberts-nathaniel-023"],
      time: new Date(2025, 7, 14, 8, 49),
    },
    "Email 2": {
      entityIds: ["smith-johnathan-151", "baxter-eleanor-004"],
      time: new Date(2025, 7, 14, 8, 56),
    },
    "Email 3": {
      entityIds: ["smith-johnathan-151", "west-josephine-126"],
      time: new Date(2025, 7, 14, 9, 2),
    },
    "Email 4": {
      entityIds: ["smith-johnathan-151", "west-josephine-126"],
      time: new Date(2025, 7, 14, 9, 27),
    },
    "Email 5": {
      entityIds: ["baxter-eleanor-004", "roberts-nathaniel-023"],
      time: new Date(2025, 7, 14, 10, 20),
    },
    "Email 6": {
      entityIds: ["roberts-nathaniel-023", "smith-johnathan-151"],
      time: new Date(2025, 7, 14, 10, 30),
    },
    "Email 7": {
      entityIds: ["west-josephine-126", "smith-johnathan-151"],
      time: new Date(2025, 7, 14, 10, 40),
    },
    "Email 8": {
      entityIds: ["smith-johnathan-151", "west-josephine-126"],
      time: new Date(2025, 7, 14, 10, 51),
    },
    "Email 9": {
      entityIds: ["west-josephine-126", "smith-johnathan-151"],
      time: new Date(2025, 7, 14, 12, 5),
    },
    "Email 10": {
      entityIds: ["smith-johnathan-151", "west-josephine-126"],
      time: new Date(2025, 7, 14, 14, 37),
    },
    "Email 11": {
      entityIds: ["baxter-eleanor-004", "west-josephine-126"],
      time: new Date(2025, 7, 14, 16, 7),
    },
    "Email 12": {
      entityIds: ["west-josephine-126", "roberts-nathaniel-023"],
      time: new Date(2025, 7, 14, 17, 42),
    },
  },
};
<!doctype html>
<html>
  <head>
    <link rel="stylesheet" href="@ci/theme/kg/css/examples.css" />
    <link rel="stylesheet" href="./style.css" />
  </head>
  <body>
    <div id="my-timeline" style="height: 100vh">
      <span id="event-label">Ella calls Nathan</span>
      <span id="entity-label">Person of Interest</span>
      <div class="box" id="entity-box"></div>
      <div class="box" id="event-box"></div>
    </div>
    <script type="module" src="./code.js"></script>
  </body>
</html>
.box,
span {
  color: rgb(196, 250, 49);
  position: absolute;
  display: none;
  z-index: 1;
  pointer-events: none;
  background-color: rgba(0, 0, 0, 0);
  padding: 0;
  margin: 0;
}

.box {
  border: 2px solid rgb(196, 250, 49);
  border-radius: 5px;
}
import React, { useRef, useState } from "react";
import { createRoot } from "react-dom/client";
import Timeline from "kronograph/react/Timeline";
import data from "./data";

const smallPadding = 6;
const bigPadding = 12;

function Label({ itemPosition, text, labelPosition }) {
  const ref = useRef();
  const span = ref.current;
  const style = {};
  if (itemPosition === null || span === null) {
    style.display = "none";
  } else {
    const { x1, x2, y1, y2 } = itemPosition;
    style.display = "block";
    if (labelPosition === "below") {
      const entityCenterX = (x1 + x2) / 2;
      Object.assign(style, {
        left: `${entityCenterX - span.offsetWidth / 2}px`,
        top: `${y2 + smallPadding}px`,
      });
    } else if (labelPosition === "top-right") {
      Object.assign(style, {
        left: `${x2 + bigPadding}px`,
        top: `${y1 - bigPadding - span.offsetHeight}px`,
      });
    }
  }

  return (
    <span ref={ref} style={style}>
      {text}
    </span>
  );
}

function Box({ itemPosition, xPadding, yPadding }) {
  const style = {};
  if (itemPosition === null) {
    style.display = "none";
  } else {
    let { x1, x2, y1, y2 } = itemPosition;
    y1 -= yPadding;
    y2 += yPadding;
    x1 -= xPadding;
    x2 += xPadding;
    Object.assign(style, {
      display: "block",
      left: `${x1}px`,
      width: `${x2 - x1}px`,
      top: `${y1}px`,
      height: `${y2 - y1}px`,
    });
  }
  return <div style={style} className="box"></div>;
}

export function Demo() {
  const timelineRef = useRef();
  const [entityPosition, setEntityPosition] = useState(null);
  const [eventPosition, setEventPosition] = useState(null);

  function updateAnnotations() {
    const timeline = timelineRef.current;
    if (timeline === null) {
      return;
    }
    setEntityPosition(timeline.getEntityPosition("west-josephine-126"));
    setEventPosition(timeline.getEventPosition("Email 5"));
  }

  return (
    <div id="wrapper" style={{ height: "100%" }}>
      <Label itemPosition={entityPosition} labelPosition={"below"} text={"Person of Interest"} />
      <Label itemPosition={eventPosition} labelPosition={"top-right"} text="Ella calls Nathan" />
      <Box itemPosition={entityPosition} xPadding={0} yPadding={smallPadding} />
      <Box itemPosition={eventPosition} xPadding={bigPadding} yPadding={bigPadding} />
      <Timeline ref={timelineRef} {...data} onTimelineDraw={updateAnnotations} />
    </div>
  );
}

const root = createRoot(document.getElementById("my-timeline"));
root.render(<Demo />);
export default {
  entities: {
    "smith-johnathan-151": {
      label: "John Smith",
    },
    "west-josephine-126": {
      label: "Josephine West",
    },
    "roberts-nathaniel-023": {
      label: "Nathan Roberts",
    },
    "baxter-eleanor-004": {
      label: "Ella Baxter",
    },
  },
  events: {
    "Email 1": {
      entityIds: ["smith-johnathan-151", "roberts-nathaniel-023"],
      time: new Date(2025, 7, 14, 8, 49),
    },
    "Email 2": {
      entityIds: ["smith-johnathan-151", "baxter-eleanor-004"],
      time: new Date(2025, 7, 14, 8, 56),
    },
    "Email 3": {
      entityIds: ["smith-johnathan-151", "west-josephine-126"],
      time: new Date(2025, 7, 14, 9, 2),
    },
    "Email 4": {
      entityIds: ["smith-johnathan-151", "west-josephine-126"],
      time: new Date(2025, 7, 14, 9, 27),
    },
    "Email 5": {
      entityIds: ["baxter-eleanor-004", "roberts-nathaniel-023"],
      time: new Date(2025, 7, 14, 10, 20),
    },
    "Email 6": {
      entityIds: ["roberts-nathaniel-023", "smith-johnathan-151"],
      time: new Date(2025, 7, 14, 10, 30),
    },
    "Email 7": {
      entityIds: ["west-josephine-126", "smith-johnathan-151"],
      time: new Date(2025, 7, 14, 10, 40),
    },
    "Email 8": {
      entityIds: ["smith-johnathan-151", "west-josephine-126"],
      time: new Date(2025, 7, 14, 10, 51),
    },
    "Email 9": {
      entityIds: ["west-josephine-126", "smith-johnathan-151"],
      time: new Date(2025, 7, 14, 12, 5),
    },
    "Email 10": {
      entityIds: ["smith-johnathan-151", "west-josephine-126"],
      time: new Date(2025, 7, 14, 14, 37),
    },
    "Email 11": {
      entityIds: ["baxter-eleanor-004", "west-josephine-126"],
      time: new Date(2025, 7, 14, 16, 7),
    },
    "Email 12": {
      entityIds: ["west-josephine-126", "roberts-nathaniel-023"],
      time: new Date(2025, 7, 14, 17, 42),
    },
  },
};
<!doctype html>
<html>
  <head>
    <link rel="stylesheet" href="@ci/theme/kg/css/examples.css" />
    <link rel="stylesheet" href="./style.css" />
  </head>
  <body>
    <div id="my-timeline" style="height: 100vh"></div>
    <script type="module" src="./code.jsx"></script>
  </body>
</html>
.box,
span {
  color: rgb(196, 250, 49);
  position: absolute;
  display: none;
  z-index: 1;
  pointer-events: none;
  background-color: rgba(0, 0, 0, 0);
  padding: 0;
  margin: 0;
}

.box {
  border: 2px solid rgb(196, 250, 49);
  border-radius: 5px;
}

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.