Overview
An event is a timeline item representing something that occurred at a specific time, involving one or more entities.
KronoGraph can visualize a variety of kinds of events:
- Events involving just one entity (such as a tweet), or multiple entities (a phone call)
- Events with different time spans:
- Instantaneous events happen at a single moment (such as a bank transfer).
- Duration events span a period of time, with separate start and end times (such as a meeting).
- Non-directional events (such as a meeting) or directional events:
- Uni-directional events (such as sender to recipient)
- Multi-directional events (between multiple inputs and outputs)
An event is shown as a vertical line connecting the entities involved at the event start time. This vertical line is called an event line. Event lines can be styled and customized using properties in the Event object.
When the timeline contains a large number of events, KronoGraph automatically aggregates them into a heatmap.
Every event is identified by an id that is unique across both entities and events.
Event Styling
You can style events to help visualize further information, such as how they relate to one another (using color), how they relate to entities (using showArrows), or their relative importance (using lineWidth). The Styling Events example allows you to explore and experiment with these settings.
You can also add event labels to them, using label to style their color and orientation, as illustrated in the Event Labels example.
Kronograph Example
Log in to view live examplesIn the example above the color and lineWidth properties have been changed for "event2".
const events = {
event1: {
entityIds: ["entity1"],
time: new Date(2025, 7, 14, 8, 56),
},
event2: {
entityIds: ["entity2", "entity1"],
time: new Date(2025, 7, 14, 8, 56, 10),
color: "#e07a5f",
lineWidth: 5,
},
};Using ping
You can draw attention to specific events dynamically, in response to user interactions, using the animated halo effect provided by ping. ping. This is shown in our Ping Animations example.
Event Types
Event types allow you to customize the appearance of multiple events in one place, and then apply those settings to multiple events.
To do this, set up an EventType object with the appearance settings to be shared, then assign that type to each event. Each event can have only one type, although event types can have a base type.
In these examples we are using a subset of the "Street Network Changes" from the City of New York. Here, the street change events are styled by the type of change. Each type of change has its own EventType where a color and fontIcon are added.
Kronograph Example
Log in to view live examplesThis is an example of how the EventTypes are shown in the data:
const eventTypes = {
"Two-way Conversion": {
color: "#227c9d",
fontIcon: {
fontFamily: "Font Awesome 6 Free",
fontWeight: 900,
text: "\uf101",
},
},
"One-way Conversion": {
color: "#ffcb77",
fontIcon: {
fontFamily: "Font Awesome 6 Free",
fontWeight: 900,
text: "\uf138",
},
},
};This is how the EventTypes are assigned to the events using the type property:
const events = {
"172 Stchange": {
entityIds: ["93 Ave", "Jamaica Ave"],
time: 1436223600000,
type: "One-way Conversion",
},
};Event Base Types
Event types can inherit properties from a base type, specified by baseType.
Kronograph Example
Log in to view live examplesIn this example each event's color is derived from its type. The fontIcon is set on the baseType of each type.
const eventTypes = {
"Street Change": {
"fontIcon": {
"fontFamily": "Font Awesome 6 Free",
"fontWeight": 900,
"text": "\uf101"
}
},
"Brooklyn": {
"color": "#17c3b2",
"baseType": "Street Change"
},
"The Bronx": {
"color": "#227c9d",
"baseType": "Street Change"
},
"Queens": {
"color": "#ffcb77";
"baseType": "Street Change"
}
}See the Inherited Styles example for more details.
Default Event Type
Events that have unspecified properties will inherit them from the default event type. Assign properties to the default event type as follows:
const eventTypes = {
default: {
color: "#EE9B00",
},
};Note the default type cannot have a baseType.
Event Summaries
KronoGraph combines individual events into an event summary when they start to appear too close together to be viewed clearly individually. This is shown as a lozenge along the entity row, using the color of the majority of the events it represents. As you zoom in, the summaries resolve into individual events again.
Kronograph Example
Log in to view live examplesEvent summaries are connected to each other vertically by a translucent band that blends the colors of the summaries at either end.
When interacting programmatically, the targetType in the event handler is 'eventSummary' and the eventIds property contains the ids of all summarized events:
function clickHandler({ targetType, eventIds }) {
// the user clicked an event or event summary
if (targetType === "event" || targetType === "eventSummary") {
console.log(`Event ids: `, eventIds);
}
}
timeline.on("click", clickHandler);const handleClick = ({ targetType, eventIds }) => {
// the user clicked an event or event summary
if (targetType === "event" || targetType === "eventSummary") {
console.log(`Event ids: `, eventIds);
}
};
<Timeline entities={entities} events={events} onTimelineClick={handleClick} />;Event Folds
When more than one instantaneous event happens at once, KronoGraph allows you to inspect them more closely in an event fold.
Because the events happen simultaneously, we imagine they are folded behind the timeline. To "unfold" them, event folds can be clicked and opened which brings the individual events into view.
The event folds are only visible once the timeline is sufficiently zoomed in so that any event summary they're part of has been resolved to single event times. Only one event fold can be open at a time.
Kronograph Example
Log in to view live examplesAll events within the fold have the same timestamp, shown by where the fold is attached to the scale. The time is accessible via the Event object, so a tooltip can be added if needed.
When interacting with the fold, the targetType in the event handler is 'fold' and the eventIds property contains the ids of the events within the fold.
function clickHandler({ targetType, eventIds }) {
// the user clicked a fold
if (targetType === "fold") {
console.log(`Events List: `, eventIds);
}
}
timeline.on("click", clickHandler);const handleClick = ({ targetType, eventIds }) => {
// the user clicked a fold
if (targetType === "fold") {
console.log(`Events List: `, eventIds);
}
};
<Timeline entities={entities} events={events} onTimelineClick={handleClick} />;Note that the targetType for the "x" to close the fold is 'foldControl'.
To explore further, see the Event Folds example.