Creating a Timeline

createTimeline(componentDefinition)
copy link
Creates a KronoGraph timeline in your web page within the specified DOM element. The timeline sets its height and width to equal the size of its parent element, or 100px if the parent does not have these. We recommend styling the parent of the timeline, not the timeline itself.
Parameters
  • componentDefinition
    copy link
    object | string
    required
    Specifies values for the timeline to be created, or the id of the container element in which to create the timeline.
      • container
        HTMLElement | string | null
        required
        The DOM element in which to insert the component. Can be either the element's id as a string or the element itself. If set to null, the created component will be detached from any DOM element.
      • options
        TimelineOptions
        Options for the new component.
Returns
Timeline
The created Timeline object.

Timeline

The Timeline component draws items passed to the set() function.

When new or updated data is passed in, it will redraw with the new items.

annotations()
copy link
Beta
Gets a copy of an object describing the timeline annotations.
Parametersnone
Returns
{ [id: string]: Annotation }
A copy of the current annotations, in a dictionary object indexed by id.
annotations(annotations)
copy link
Beta
Sets the timeline annotations, replacing any existing annotations.
Parameters
Returns
{ [id: string]: Annotation }
A copy of the current annotations, in a dictionary object indexed by id.
destroy()
copy link
Destroys the current instance of the timeline, freeing any allocated resources.
Parametersnone
Returns
void
expandedRows(mode, ids)
copy link
Beta
Expands entities by adding sub-rows to vertically space out events as specified by the expandedRows options. See also Expanded Rows.
Parameters
  • mode
    copy link
    'auto' | 'manual'default:manual
    required
    How KronoGraph determines which entity rows to expand, if space allows:
    • 'auto' - Expand all entity rows, as needed.
    • 'manual' - Expand just the rows of entities specified in the list of ids.
  • ids
    copy link
    string | string[]
    If mode is 'manual', the ids of the entities whose rows are to be expanded.
Returns
ExpandedRows
An object containing the ids of the entities whose rows are to be expanded, and the expansion mode being used.
expandedRows()
copy link
Beta
Expands entities by adding sub-rows to vertically space out events as specified by the expandedRows options. See also Expanded Rows.
Parametersnone
Returns
ExpandedRows
An object containing the ids of the entities whose rows are to be expanded, and the expansion mode being used.
export(options)
copy link
async
Exports a static image of the timeline. The exported image is encoded in a blob URL.
Parameters
  • options
    copy link
    ExportOptions
    required
    Options related to producing an export of the current view.
      • includeAnnotations
        booleandefault:true
        Whether to include annotations in the output.
      • type
        'png'
        required
        The file type of the output.
Returns
Promise<ExportResult>
A promise that will resolve with an object containing the blob URL of the exported image or reject with an error.
fit()
copy link
Fits all the events and time series chart data points into the viewport. If Scale Wrapping is used, fits the wrapped time range into the viewport.
Parametersnone
Returns
void
focus(focusIds)
copy link
Sets the timeline focus to the specified entities or events. When the timeline is focused, only focused items and their connections are shown. Focused events will keep the entities they are linked to in focus. Focusing does not affect time series charts.
Parameters
  • focusIds
    copy link
    string | string[]
    required
    The id or ids of the entities or events to focus on.
Returns
string[]
The ids of the focused items.
focus()
copy link
Gets the ids of the focused entities or events. When focus items are set, only those items and their connections are shown.
Parametersnone
Returns
string[]
The ids of the focused items.
getAnnotationBodyPosition(annotationId)
copy link
Beta
Gets an object describing the position of an annotation's body.
Parameters
  • annotationId
    copy link
    string
    required
    The id of the annotation.
Returns
AnnotationBodyPosition | null
An AnnotationBodyPosition object, or null if the annotation is not shown in the timeline.
getEntity(entityId)
copy link
Returns a copy of the entity with the specified id.
Parameters
  • entityId
    copy link
    string
    required
    The id of the entity to be retrieved.
Returns
object | null
A copy of the Entity object, or null if there is no entity with the specified id.
getEntityPosition(entityId)
copy link
Gets an object describing the position of an entity.
Parameters
  • entityId
    copy link
    string
    required
    The id of the entity.
Returns
EntityPosition | null
An EntityPosition object, or null if the entity is not shown in the timeline.
getEvent(eventId)
copy link
Returns a copy of the event with the specified id.
Parameters
  • eventId
    copy link
    string
    required
    The id of the event to be retrieved.
Returns
object | null
A copy of the Event object, or null if there is no event with the specified id.
getEventPosition(eventId)
copy link
Gets an object describing the position of an event.
Parameters
  • eventId
    copy link
    string
    required
    The id of the event.
Returns
EventPosition | null
An EventPosition object, or null if the event is not in the current timeline range.
getInRangeItems(options)
copy link
Returns an object detailing the ids of events and entities that are in the current range.
Parameters
  • options
    copy link
    object
    Specifies which items are included.
      • focus
        booleandefault:true
        If there is an entity that is focused, then this option defines whether to include just the focused entity and its neighbors. Otherwise all events and entities in the current range are included.
Returns
{ entities: Object, events: Object }
Objects whose keys are the ids of entities and events in the current range.
getPinnedEntityIds()
copy link
Returns the ids of entities that are pinned.
Parametersnone
Returns
string[]
The ids of the pinned items.
getRowEntityIds(rowId)
copy link
Returns the ids of the entities in the specified row.
Parameters
  • rowId
    copy link
    string
    required
    The id of the row.
Returns
string[] | null
An array of the entity ids, or null if there is no entity row with the specified id.
highlight()
copy link
Gets the ids of highlighted rows and entities.
Parametersnone
Returns
string[]
The ids of highlighted rows and entities.
highlight(highlightIds)
copy link
Sets the highlighted rows and entities. Highlighted rows and entities are drawn with a distinct highlightColor.
Parameters
  • highlightIds
    copy link
    string | string[]
    required
    The ids of the highlighted rows and entities.
Returns
string[]
The ids of highlighted rows and entities.
inRange(item, nanoseconds)
copy link
Determines whether a time or event is within the timeline's visible range.
Parameters
  • item
    copy link
    Date | number | TimeRange | string
    required
    A Date in local time, a millisecond number in UTC, a TimeRange object, or the id of an event.
  • nanoseconds
    copy link
    number
    The number of nanoseconds to add to the Date or number.
Returns
boolean
Whether the specified item is within the timeline's visible range.
isHeatmapShown()
copy link
Determines whether the heatmap is currently shown.
Parametersnone
Returns
boolean
True if the heatmap is currently shown, otherwise false.
labelAreaWidth()
copy link
Gets the mode of calculation for the width of the entity label area and its width.
Parametersnone
Returns
LabelAreaWidth
An object containing the mode of calculation for the width of the entity label area and its width.
labelAreaWidth(mode, width)
copy link
Sets the mode of calculation for the width of the entity label area and, if 'fixed', its width.
Parameters
  • mode
    copy link
    'auto' | 'fixed'default:auto
    required
    The mode of calculation for the width of the entity label area:
    • 'auto' - The width is calculated automatically based on the visible entities.
    • 'fixed' - The width is fixed, but draggable.
  • width
    copy link
    number
    The width of the entity label area.
Returns
LabelAreaWidth
An object containing the mode of calculation for the width of the entity label area and its width.
lens()
copy link
Gets the id of the entity at the center of the lens view.
Parametersnone
Returns
string | null
The id of the entity at the center of the lens view, or null if lens view isn't open.
lens(entityId)
copy link
Sets the entity at the center of the lens view. Set it to null to close lens view.
Parameters
  • entityId
    copy link
    string | null
    required
    The id of the entity.
Returns
string | null
The id of the entity at the center of the lens, or null if lens view isn't open.
markers()
copy link
Gets a copy of the timeline markers.
Parametersnone
Returns
Marker[]
A copy of the current markers.
markers(markers)
copy link
Sets the timeline markers.
Parameters
  • markers
    copy link
    Marker[]
    required
    An array of markers to add.
Returns
Marker[]
A copy of the current markers.
off(name, handler)
copy link
Detaches an event handler from an event fired by the timeline. See Handling Events.
Parameters
  • name
    copy link
    string
    required
    The name of the event.
  • handler
    copy link
    Function
    required
    The handler for the event.
Returns
void
on(name, handler)
copy link
Attaches an event handler to an event fired by the timeline. See Handling Events.
Parameters
  • name
    copy link
    string
    required
    The name of the event.
  • handler
    copy link
    Function
    required
    The handler for the event.
Returns
void
options()
copy link
Gets the current timeline options.
Parametersnone
Returns
TimelineOptions
The currently specified options.
options(options)
copy link
Sets the timeline options.
Parameters
Returns
TimelineOptions
The currently specified options.
pan(direction, amount)
copy link
Pans the timeline in the specified direction. The panning range is limited and depends on the timeline data.
Parameters
  • direction
    copy link
    'left' | 'right'
    required
    Specifies the direction to pan the timeline in.
  • amount
    copy link
    numberdefault:0.3
    How far to pan the timeline. The distance is measured as a proportion of space across the visible timeline range.
Returns
void
pin(entityId, pinned)
copy link
Pins or unpins the specified entities. Pinned entities are always shown separately from entity groups.
Parameters
  • entityId
    copy link
    string | string[]
    required
    The id or ids of the entities to set the pin state for.
  • pinned
    copy link
    booleandefault:true
    Controls if the entities should be pinned or unpinned.
Returns
void
ping(id, options)
copy link
Adds an animated effect to a specified event or events, and then removes it again.
Parameters
  • id
    copy link
    string | string[]
    required
    The id or ids of the events to ping.
  • options
    copy link
    object
    Options to control the animation.
      • color
        stringdefault:'#909090'
        The color to use for the animated effect.
      • mode
        'individual' | 'grouped'default:'individual'
        Whether the specified events should each have their own ping animation, or all events have a single outer ping animation.
      • repeat
        numberdefault:1
        The number of times the animation should be repeated.
      • spread
        numberdefault:42
        The distance between the start and the end of the ping stroke, in pixels.
      • strokeWidth
        numberdefault:12
        The width of the ping stroke at the end of the animation, in pixels.
      • time
        numberdefault:800
        The time the animation should take, in milliseconds.
Returns
void
range()
copy link
Gets the range of time currently shown in the timeline. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
Parametersnone
Returns
object
An object containing the range of visible times:
  • start the start of the visible time range, as a Date object.
  • end the end of the visible time range, as a Date object.
  • startNanoseconds the number of nanoseconds to add to start.
  • endNanoseconds the number of nanoseconds to add to end.
range(start, end, startNanoseconds, endNanoseconds)
copy link
Sets the range of times currently shown by the timeline. When the scale is wrapped, this is relative to the base range - see Scale Wrapping. There are limits to the range that can be set, which depend on the timeline data.
Parameters
  • start
    copy link
    Date | number
    required
    The start of the range as a Date in local time, or a millisecond number in UTC.
  • end
    copy link
    Date | number
    required
    The end of the range as a Date in local time, or a millisecond number in UTC.
  • startNanoseconds
    copy link
    number
    The number of nanoseconds to add to start.
  • endNanoseconds
    copy link
    number
    The number of nanoseconds to add to end.
Returns
object
An object containing the range of visible times:
  • start the start of the visible time range, as a Date object.
  • end the end of the visible time range, as a Date object.
  • startNanoseconds the number of nanoseconds to add to start.
  • endNanoseconds the number of nanoseconds to add to end.
reveal()
copy link
Gets the event ids of all revealed events.
Parametersnone
Returns
string[]
The ids of the revealed events.
reveal(revealIds)
copy link
Sets the underlying events to be revealed when the heatmap view is shown.
Parameters
  • revealIds
    copy link
    string | string[]
    required
    The id or ids of the events to reveal.
Returns
string[]
The ids of the revealed events.
selection()
copy link
Beta
Gets the ids of the selected events.
Parametersnone
Returns
string[]
The ids of the selected events.
selection(eventIds)
copy link
Beta
Sets the selected events. Selected events are drawn with a highlight.
Parameters
  • eventIds
    copy link
    string | string[]
    required
    The id or ids of the events to select.
Returns
string[]
The ids of the selected events.
selectionMode()
copy link
Beta
Gets a flag indicating whether the timeline is in selection mode.
Parametersnone
Returns
boolean
True if the timeline is in selection mode, otherwise false.
selectionMode(mode)
copy link
Beta
Sets the selection mode.
Parameters
  • mode
    copy link
    boolean
    required
    True to put the timeline in selection mode, otherwise false.
Returns
boolean
True if the timeline is in selection mode, otherwise false.
set(data)
copy link
Replaces the timeline data with the new data specified. Any existing items in the timeline will be removed. See Data Formats.
Parameters
  • data
    copy link
    TimelineData
    required
    The data to load into the timeline.
Returns
void
setContainer(element)
copy link
Sets the location of the timeline in the DOM. Set to null to temporarily remove the timeline.
Parameters
  • element
    copy link
    string | HTMLElement | null
    The DOM element that the chart should be appended to, or null to detach it.
Returns
void
setOrdering(orderingName)
copy link
Sets the type of entity ordering to use in the timeline.
Parameters
  • orderingName
    copy link
    'firstevent' | 'lastevent' | 'keyorder' | 'alphabetical' | 'shorteneventlines'
    required
    The name of the ordering to use.
Returns
void
zoom(direction)
copy link
Zoom the timeline in the manner specified. The zooming range is limited and depends on the timeline data.
Parameters
  • direction
    copy link
    'in' | 'out'
    required
    Specifies how to zoom the timeline.
Returns
void

Handling Events

KronoGraph lets you respond to various events fired by the timeline, which can be triggered either by user interaction or by items changing in the timeline.

Use the on() function to attach an event handler to an event. To detach it, use the off() function.

When an event fires, any attached event handlers are passed a single object containing all the details of the event.

To override the default behavior of an event, call the preventDefault() function in the event handler.

annotations

Beta
Fires when the current annotations change.
  • annotations
    copy link
    { [id: string]: Annotation }
    required
    The current set of annotations.
  • why
    copy link
    ChangeReason
    required
    The reason this event was fired:
    • 'auto' - The event was triggered by internal KronoGraph state.
    • 'user' - The event was triggered by user action.

click

Fires when the user clicks or taps on the timeline.
Default actions:
  • Focus control - Focuses or unfocuses the entity row.
  • Pin control - Pins or unpins the entity row.
  • Annotation delete control - Deletes the annotation.
  • button
    copy link
    number
    required
    The index of the button used.
  • defaultPrevented
    copy link
    boolean
    required
    A read-only value indicating whether the default action was prevented.
  • endNanoseconds
    copy link
    number
    required
    The number of nanoseconds to add to endTime.
  • endTime
    copy link
    Date
    required
    The end of the time range covered by the targeted item. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
  • eventIds
    copy link
    string[]
    required
    An array of ids of events within the targeted item. Only defined if targetType is event, eventSummary or cell.
  • id
    copy link
    string | null
    required
    The id of the targeted item.
  • label
    copy link
    string
    required
    The label of the targeted item.
  • modifierKeys
    copy link
    EventModifierKeys
    required
    An object describing which modifier keys were pressed when the event occurred.
  • pointerId
    copy link
    number
    required
    The unique identifier of the pointer.
  • pointerType
    copy link
    string
    required
    The type of pointing device: mouse, touch or pen.
  • preventDefault()
    copy link
    If called, the default action is prevented.
    Parametersnone
    Returns
    void
  • startNanoseconds
    copy link
    number
    required
    The number of nanoseconds to add to startTime.
  • startTime
    copy link
    Date
    required
    The start of the time range covered by the targeted item. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
  • subItem
    copy link
    SubItem
    required
    An object containing details of the sub-item, or undefined if the cursor is not over a sub-item.
  • targetType
    copy link
    'annotationBody' | 'annotationDeleteButton' | 'annotationEditButton' | 'annotation' | 'cell' | 'entity' | 'entityGroup' | 'entityRun' | 'event' | 'eventSummary' | 'eventLabel' | 'focus' | 'fold' | 'glyph' | 'labelAreaBorder' | 'lensControl' | 'lensScrollbar' | 'pin' | 'scale' | 'timeSeriesChart' | null
    required
    The type of the targeted item.
  • time
    copy link
    Date
    required
    The timeline time corresponding to the pointer position. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
  • timeNanoseconds
    copy link
    number
    required
    The number of nanoseconds to add to time.
  • x
    copy link
    number
    required
    The distance from the left edge of the Timeline element to the pointer position.
  • y
    copy link
    number
    required
    The distance from the top edge of the Timeline element to the pointer position.

context-menu

Fires on a right click or a long press on the timeline.
Default action:
  • Suppresses the click event.
  • button
    copy link
    number
    required
    The index of the button used.
  • defaultPrevented
    copy link
    boolean
    required
    A read-only value indicating whether the default action was prevented.
  • endNanoseconds
    copy link
    number
    required
    The number of nanoseconds to add to endTime.
  • endTime
    copy link
    Date
    required
    The end of the time range covered by the targeted item. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
  • eventIds
    copy link
    string[]
    required
    An array of ids of events within the targeted item. Only defined if targetType is event, eventSummary or cell.
  • id
    copy link
    string | null
    required
    The id of the targeted item.
  • label
    copy link
    string
    required
    The label of the targeted item.
  • modifierKeys
    copy link
    EventModifierKeys
    required
    An object describing which modifier keys were pressed when the event occurred.
  • pointerId
    copy link
    number
    required
    The unique identifier of the pointer.
  • pointerType
    copy link
    string
    required
    The type of pointing device: mouse, touch or pen.
  • preventDefault()
    copy link
    If called, the default action is prevented.
    Parametersnone
    Returns
    void
  • startNanoseconds
    copy link
    number
    required
    The number of nanoseconds to add to startTime.
  • startTime
    copy link
    Date
    required
    The start of the time range covered by the targeted item. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
  • subItem
    copy link
    SubItem
    required
    An object containing details of the sub-item, or undefined if the cursor is not over a sub-item.
  • targetType
    copy link
    'annotationBody' | 'annotationDeleteButton' | 'annotationEditButton' | 'annotation' | 'cell' | 'entity' | 'entityGroup' | 'entityRun' | 'event' | 'eventSummary' | 'eventLabel' | 'focus' | 'fold' | 'glyph' | 'labelAreaBorder' | 'lensControl' | 'lensScrollbar' | 'pin' | 'scale' | 'timeSeriesChart' | null
    required
    The type of the targeted item.
  • time
    copy link
    Date
    required
    The timeline time corresponding to the pointer position. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
  • timeNanoseconds
    copy link
    number
    required
    The number of nanoseconds to add to time.
  • x
    copy link
    number
    required
    The distance from the left edge of the Timeline element to the pointer position.
  • y
    copy link
    number
    required
    The distance from the top edge of the Timeline element to the pointer position.

double-click

Fires on a double click or a double tap on the timeline.
Default actions:
  • On the background - Unfocuses any focused entity rows.
  • On an entity row - Focuses or unfocuses the entity row.
  • On the scale - Sets the timeline range to the startTime and endTime properties of the selected scale item.
  • button
    copy link
    number
    required
    The index of the button used.
  • defaultPrevented
    copy link
    boolean
    required
    A read-only value indicating whether the default action was prevented.
  • endNanoseconds
    copy link
    number
    required
    The number of nanoseconds to add to endTime.
  • endTime
    copy link
    Date
    required
    The end of the time range covered by the targeted item. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
  • eventIds
    copy link
    string[]
    required
    An array of ids of events within the targeted item. Only defined if targetType is event, eventSummary or cell.
  • id
    copy link
    string | null
    required
    The id of the targeted item.
  • label
    copy link
    string
    required
    The label of the targeted item.
  • modifierKeys
    copy link
    EventModifierKeys
    required
    An object describing which modifier keys were pressed when the event occurred.
  • pointerId
    copy link
    number
    required
    The unique identifier of the pointer.
  • pointerType
    copy link
    string
    required
    The type of pointing device: mouse, touch or pen.
  • preventDefault()
    copy link
    If called, the default action is prevented.
    Parametersnone
    Returns
    void
  • startNanoseconds
    copy link
    number
    required
    The number of nanoseconds to add to startTime.
  • startTime
    copy link
    Date
    required
    The start of the time range covered by the targeted item. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
  • subItem
    copy link
    SubItem
    required
    An object containing details of the sub-item, or undefined if the cursor is not over a sub-item.
  • targetType
    copy link
    'annotationBody' | 'annotationDeleteButton' | 'annotationEditButton' | 'annotation' | 'cell' | 'entity' | 'entityGroup' | 'entityRun' | 'event' | 'eventSummary' | 'eventLabel' | 'focus' | 'fold' | 'glyph' | 'labelAreaBorder' | 'lensControl' | 'lensScrollbar' | 'pin' | 'scale' | 'timeSeriesChart' | null
    required
    The type of the targeted item.
  • time
    copy link
    Date
    required
    The timeline time corresponding to the pointer position. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
  • timeNanoseconds
    copy link
    number
    required
    The number of nanoseconds to add to time.
  • x
    copy link
    number
    required
    The distance from the left edge of the Timeline element to the pointer position.
  • y
    copy link
    number
    required
    The distance from the top edge of the Timeline element to the pointer position.

drag-end

Fires when the drag is finished and pointer is released, or when the drag is canceled. On touch devices this fires when the finger or pointing device is lifted.
Default action:
  • On MarqueeRange drag type - the timeline will zoom into the selected range.
  • button
    copy link
    number
    required
    The index of the button used.
  • defaultPrevented
    copy link
    boolean
    required
    A read-only value indicating whether the default action was prevented.
  • dragType
    copy link
    'annotationScrollBar' | 'labelAreaWidth' | 'lensScrollbar' | 'marqueeRange' | 'marqueeSelection' | 'moveAnnotation' | 'pan' | null
    required
    The type of drag.
  • endNanoseconds
    copy link
    number
    required
    The number of nanoseconds to add to endTime.
  • endTime
    copy link
    Date
    required
    The end of the time range covered by the targeted item. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
  • entityRangeSubject
    copy link
    EntityRangeSubject
    required
    The entity range within the dragged area. Only present when dragType is 'marqueeSelection'.
  • eventIds
    copy link
    string[]
    required
    An array of ids of events within the targeted item. Only defined if targetType is event, eventSummary or cell.
  • id
    copy link
    string | null
    required
    The id of the targeted item.
  • label
    copy link
    string
    required
    The label of the targeted item.
  • modifierKeys
    copy link
    EventModifierKeys
    required
    An object describing which modifier keys were pressed when the event occurred.
  • pointerId
    copy link
    number
    required
    The unique identifier of the pointer.
  • pointerType
    copy link
    string
    required
    The type of pointing device: mouse, touch or pen.
  • preventDefault()
    copy link
    If called, the default action is prevented.
    Parametersnone
    Returns
    void
  • startNanoseconds
    copy link
    number
    required
    The number of nanoseconds to add to startTime.
  • startTime
    copy link
    Date
    required
    The start of the time range covered by the targeted item. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
  • subItem
    copy link
    SubItem
    required
    An object containing details of the sub-item, or undefined if the cursor is not over a sub-item.
  • targetType
    copy link
    'annotationBody' | 'annotationDeleteButton' | 'annotationEditButton' | 'annotation' | 'cell' | 'entity' | 'entityGroup' | 'entityRun' | 'event' | 'eventSummary' | 'eventLabel' | 'focus' | 'fold' | 'glyph' | 'labelAreaBorder' | 'lensControl' | 'lensScrollbar' | 'pin' | 'scale' | 'timeSeriesChart' | null
    required
    The type of the targeted item.
  • time
    copy link
    Date
    required
    The timeline time corresponding to the pointer position. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
  • timeNanoseconds
    copy link
    number
    required
    The number of nanoseconds to add to time.
  • x
    copy link
    number
    required
    The distance from the left edge of the Timeline element to the pointer position.
  • y
    copy link
    number
    required
    The distance from the top edge of the Timeline element to the pointer position.

drag-move

Fires continuously as the cursor moves during a drag.
  • button
    copy link
    number
    required
    The index of the button used.
  • defaultPrevented
    copy link
    boolean
    required
    A read-only value indicating whether the default action was prevented.
  • dragType
    copy link
    'annotationScrollBar' | 'labelAreaWidth' | 'lensScrollbar' | 'marqueeRange' | 'marqueeSelection' | 'moveAnnotation' | 'pan' | null
    required
    The type of drag.
  • endNanoseconds
    copy link
    number
    required
    The number of nanoseconds to add to endTime.
  • endTime
    copy link
    Date
    required
    The end of the time range covered by the targeted item. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
  • eventIds
    copy link
    string[]
    required
    An array of ids of events within the targeted item. Only defined if targetType is event, eventSummary or cell.
  • id
    copy link
    string | null
    required
    The id of the targeted item.
  • label
    copy link
    string
    required
    The label of the targeted item.
  • modifierKeys
    copy link
    EventModifierKeys
    required
    An object describing which modifier keys were pressed when the event occurred.
  • pointerId
    copy link
    number
    required
    The unique identifier of the pointer.
  • pointerType
    copy link
    string
    required
    The type of pointing device: mouse, touch or pen.
  • preventDefault()
    copy link
    If called, the default action is prevented.
    Parametersnone
    Returns
    void
  • startNanoseconds
    copy link
    number
    required
    The number of nanoseconds to add to startTime.
  • startTime
    copy link
    Date
    required
    The start of the time range covered by the targeted item. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
  • subItem
    copy link
    SubItem
    required
    An object containing details of the sub-item, or undefined if the cursor is not over a sub-item.
  • targetType
    copy link
    'annotationBody' | 'annotationDeleteButton' | 'annotationEditButton' | 'annotation' | 'cell' | 'entity' | 'entityGroup' | 'entityRun' | 'event' | 'eventSummary' | 'eventLabel' | 'focus' | 'fold' | 'glyph' | 'labelAreaBorder' | 'lensControl' | 'lensScrollbar' | 'pin' | 'scale' | 'timeSeriesChart' | null
    required
    The type of the targeted item.
  • time
    copy link
    Date
    required
    The timeline time corresponding to the pointer position. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
  • timeNanoseconds
    copy link
    number
    required
    The number of nanoseconds to add to time.
  • x
    copy link
    number
    required
    The distance from the left edge of the Timeline element to the pointer position.
  • y
    copy link
    number
    required
    The distance from the top edge of the Timeline element to the pointer position.

drag-start

Fires when a drag is started. Use setDragOptions to set the dragging behavior.
Default actions:
  • On the background - Pans the timeline.
  • On the scale - Draws a marquee range. On drag-end, the default action is to zoom into the selected range.
  • On the entity label area border - Adjusts the label area width.
  • button
    copy link
    number
    required
    The index of the button used.
  • defaultPrevented
    copy link
    boolean
    required
    A read-only value indicating whether the default action was prevented.
  • dragType
    copy link
    'annotationScrollBar' | 'labelAreaWidth' | 'lensScrollbar' | 'marqueeRange' | 'marqueeSelection' | 'moveAnnotation' | 'pan' | null
    required
    The type of drag.
  • endNanoseconds
    copy link
    number
    required
    The number of nanoseconds to add to endTime.
  • endTime
    copy link
    Date
    required
    The end of the time range covered by the targeted item. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
  • eventIds
    copy link
    string[]
    required
    An array of ids of events within the targeted item. Only defined if targetType is event, eventSummary or cell.
  • id
    copy link
    string | null
    required
    The id of the targeted item.
  • label
    copy link
    string
    required
    The label of the targeted item.
  • modifierKeys
    copy link
    EventModifierKeys
    required
    An object describing which modifier keys were pressed when the event occurred.
  • pointerId
    copy link
    number
    required
    The unique identifier of the pointer.
  • pointerType
    copy link
    string
    required
    The type of pointing device: mouse, touch or pen.
  • preventDefault()
    copy link
    If called, the default action is prevented.
    Parametersnone
    Returns
    void
  • setDragOptions(options)
    copy link
    Controls the dragging behavior.
    Parameters
    • options
      copy link
      DraggerOptions
      required
      Options to control the dragging behavior.
    Returns
    void
  • startNanoseconds
    copy link
    number
    required
    The number of nanoseconds to add to startTime.
  • startTime
    copy link
    Date
    required
    The start of the time range covered by the targeted item. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
  • subItem
    copy link
    SubItem
    required
    An object containing details of the sub-item, or undefined if the cursor is not over a sub-item.
  • targetType
    copy link
    'annotationBody' | 'annotationDeleteButton' | 'annotationEditButton' | 'annotation' | 'cell' | 'entity' | 'entityGroup' | 'entityRun' | 'event' | 'eventSummary' | 'eventLabel' | 'focus' | 'fold' | 'glyph' | 'labelAreaBorder' | 'lensControl' | 'lensScrollbar' | 'pin' | 'scale' | 'timeSeriesChart' | null
    required
    The type of the targeted item.
  • time
    copy link
    Date
    required
    The timeline time corresponding to the pointer position. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
  • timeNanoseconds
    copy link
    number
    required
    The number of nanoseconds to add to time.
  • x
    copy link
    number
    required
    The distance from the left edge of the Timeline element to the pointer position.
  • y
    copy link
    number
    required
    The distance from the top edge of the Timeline element to the pointer position.

draw

Fires each time the timeline is drawn. The handler for this event is not passed any arguments.

expandedRows

Beta
Fires when the set of entities whose rows are to be expanded (if space allows) changes.
  • mode
    copy link
    'auto' | 'manual'
    required
    The mode used to determine which entity rows to expand (if space allows).
  • expandedRowIds
    copy link
    string[]
    required
    The ids of the entities whose rows are to be expanded (if space).
  • why
    copy link
    ChangeReason
    required
    The reason this event was fired:
    • 'auto' - The event was triggered by internal KronoGraph state.
    • 'user' - The event was triggered by user action.

focus

Fires when the list of focused items changes.
  • focus
    copy link
    string[]
    required
    The ids of items that are in focus.
  • why
    copy link
    ChangeReason
    required
    The reason this event was fired:
    • 'auto' - The event was triggered by internal KronoGraph state.
    • 'user' - The event was triggered by user action.

highlight

Fires when the list of highlighted items changes.
  • highlight
    copy link
    string[]
    required
    The ids of the highlighted rows and entities.
  • why
    copy link
    ChangeReason
    required
    The reason this event was fired:
    • 'auto' - The event was triggered by internal KronoGraph state.
    • 'user' - The event was triggered by user action.

hover

Fires when the user hovers over the timeline. Pass the hover property to the options() function to configure the hover delay.
  • button
    copy link
    number
    required
    The index of the button used.
  • defaultPrevented
    copy link
    boolean
    required
    A read-only value indicating whether the default action was prevented.
  • endNanoseconds
    copy link
    number
    required
    The number of nanoseconds to add to endTime.
  • endTime
    copy link
    Date
    required
    The end of the time range covered by the targeted item. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
  • eventIds
    copy link
    string[]
    required
    An array of ids of events within the targeted item. Only defined if targetType is event, eventSummary or cell.
  • id
    copy link
    string | null
    required
    The id of the targeted item.
  • label
    copy link
    string
    required
    The label of the targeted item.
  • modifierKeys
    copy link
    EventModifierKeys
    required
    An object describing which modifier keys were pressed when the event occurred.
  • pointerId
    copy link
    number
    required
    The unique identifier of the pointer.
  • pointerType
    copy link
    string
    required
    The type of pointing device: mouse, touch or pen.
  • preventDefault()
    copy link
    If called, the default action is prevented.
    Parametersnone
    Returns
    void
  • startNanoseconds
    copy link
    number
    required
    The number of nanoseconds to add to startTime.
  • startTime
    copy link
    Date
    required
    The start of the time range covered by the targeted item. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
  • subItem
    copy link
    SubItem
    required
    An object containing details of the sub-item, or undefined if the cursor is not over a sub-item.
  • targetType
    copy link
    'annotationBody' | 'annotationDeleteButton' | 'annotationEditButton' | 'annotation' | 'cell' | 'entity' | 'entityGroup' | 'entityRun' | 'event' | 'eventSummary' | 'eventLabel' | 'focus' | 'fold' | 'glyph' | 'labelAreaBorder' | 'lensControl' | 'lensScrollbar' | 'pin' | 'scale' | 'timeSeriesChart' | null
    required
    The type of the targeted item.
  • time
    copy link
    Date
    required
    The timeline time corresponding to the pointer position. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
  • timeNanoseconds
    copy link
    number
    required
    The number of nanoseconds to add to time.
  • x
    copy link
    number
    required
    The distance from the left edge of the Timeline element to the pointer position.
  • y
    copy link
    number
    required
    The distance from the top edge of the Timeline element to the pointer position.

key-down

Fires when the user presses a key.
Default actions:
  • Escape key - Cancels an active drag.
  • Shift key - Draws a marquee range when dragging.
  • defaultPrevented
    copy link
    boolean
    required
    A read-only value indicating whether the default action was prevented.
  • keyCode
    copy link
    number
    required
    The keyCode of the key pressed.
  • modifierKeys
    copy link
    EventModifierKeys
    required
    An object describing which modifier keys were pressed when the event occurred.
  • preventDefault()
    copy link
    If called, the default action is prevented.
    Parametersnone
    Returns
    void

key-up

Fires when the user releases a key.
  • defaultPrevented
    copy link
    boolean
    required
    A read-only value indicating whether the default action was prevented.
  • keyCode
    copy link
    number
    required
    The keyCode of the key pressed.
  • modifierKeys
    copy link
    EventModifierKeys
    required
    An object describing which modifier keys were pressed when the event occurred.
  • preventDefault()
    copy link
    If called, the default action is prevented.
    Parametersnone
    Returns
    void

lens

Fires when the entity at the center of the lens changes, for example, when the user scrolls through lens view.
  • lens
    copy link
    string | null
    required
    The id of the entity in the center of the lens or null if lens view is not open.
  • why
    copy link
    ChangeReason
    required
    The reason this event was fired:
    • 'auto' - The event was triggered by internal KronoGraph state.
    • 'user' - The event was triggered by user action.

pin

Fires when an entity is pinned or unpinned.
  • pin
    copy link
    string[]
    required
    The ids of entities that are pinned.
  • why
    copy link
    ChangeReason
    required
    The reason this event was fired:
    • 'auto' - The event was triggered by internal KronoGraph state.
    • 'user' - The event was triggered by user action.

pointer-down

Fires when a pointer presses down on the timeline.
  • button
    copy link
    number
    required
    The index of the button used.
  • defaultPrevented
    copy link
    boolean
    required
    A read-only value indicating whether the default action was prevented.
  • endNanoseconds
    copy link
    number
    required
    The number of nanoseconds to add to endTime.
  • endTime
    copy link
    Date
    required
    The end of the time range covered by the targeted item. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
  • eventIds
    copy link
    string[]
    required
    An array of ids of events within the targeted item. Only defined if targetType is event, eventSummary or cell.
  • id
    copy link
    string | null
    required
    The id of the targeted item.
  • label
    copy link
    string
    required
    The label of the targeted item.
  • modifierKeys
    copy link
    EventModifierKeys
    required
    An object describing which modifier keys were pressed when the event occurred.
  • pointerId
    copy link
    number
    required
    The unique identifier of the pointer.
  • pointerType
    copy link
    string
    required
    The type of pointing device: mouse, touch or pen.
  • preventDefault()
    copy link
    If called, the default action is prevented.
    Parametersnone
    Returns
    void
  • startNanoseconds
    copy link
    number
    required
    The number of nanoseconds to add to startTime.
  • startTime
    copy link
    Date
    required
    The start of the time range covered by the targeted item. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
  • subItem
    copy link
    SubItem
    required
    An object containing details of the sub-item, or undefined if the cursor is not over a sub-item.
  • targetType
    copy link
    'annotationBody' | 'annotationDeleteButton' | 'annotationEditButton' | 'annotation' | 'cell' | 'entity' | 'entityGroup' | 'entityRun' | 'event' | 'eventSummary' | 'eventLabel' | 'focus' | 'fold' | 'glyph' | 'labelAreaBorder' | 'lensControl' | 'lensScrollbar' | 'pin' | 'scale' | 'timeSeriesChart' | null
    required
    The type of the targeted item.
  • time
    copy link
    Date
    required
    The timeline time corresponding to the pointer position. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
  • timeNanoseconds
    copy link
    number
    required
    The number of nanoseconds to add to time.
  • x
    copy link
    number
    required
    The distance from the left edge of the Timeline element to the pointer position.
  • y
    copy link
    number
    required
    The distance from the top edge of the Timeline element to the pointer position.

pointer-move

Fires continuously as the pointer moves on the timeline, or the timeline moves beneath the pointer.
Default action:
  • On an entity row - Highlights the entity row and displays available controls (pin or focus).
  • On a time series chart - Highlights the nearest data point.
  • button
    copy link
    number
    required
    The index of the button used.
  • defaultPrevented
    copy link
    boolean
    required
    A read-only value indicating whether the default action was prevented.
  • endNanoseconds
    copy link
    number
    required
    The number of nanoseconds to add to endTime.
  • endTime
    copy link
    Date
    required
    The end of the time range covered by the targeted item. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
  • eventIds
    copy link
    string[]
    required
    An array of ids of events within the targeted item. Only defined if targetType is event, eventSummary or cell.
  • id
    copy link
    string | null
    required
    The id of the targeted item.
  • label
    copy link
    string
    required
    The label of the targeted item.
  • modifierKeys
    copy link
    EventModifierKeys
    required
    An object describing which modifier keys were pressed when the event occurred.
  • pointerId
    copy link
    number
    required
    The unique identifier of the pointer.
  • pointerType
    copy link
    string
    required
    The type of pointing device: mouse, touch or pen.
  • preventDefault()
    copy link
    If called, the default action is prevented.
    Parametersnone
    Returns
    void
  • startNanoseconds
    copy link
    number
    required
    The number of nanoseconds to add to startTime.
  • startTime
    copy link
    Date
    required
    The start of the time range covered by the targeted item. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
  • subItem
    copy link
    SubItem
    required
    An object containing details of the sub-item, or undefined if the cursor is not over a sub-item.
  • targetType
    copy link
    'annotationBody' | 'annotationDeleteButton' | 'annotationEditButton' | 'annotation' | 'cell' | 'entity' | 'entityGroup' | 'entityRun' | 'event' | 'eventSummary' | 'eventLabel' | 'focus' | 'fold' | 'glyph' | 'labelAreaBorder' | 'lensControl' | 'lensScrollbar' | 'pin' | 'scale' | 'timeSeriesChart' | null
    required
    The type of the targeted item.
  • time
    copy link
    Date
    required
    The timeline time corresponding to the pointer position. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
  • timeNanoseconds
    copy link
    number
    required
    The number of nanoseconds to add to time.
  • x
    copy link
    number
    required
    The distance from the left edge of the Timeline element to the pointer position.
  • y
    copy link
    number
    required
    The distance from the top edge of the Timeline element to the pointer position.

pointer-up

Fires when the pointer is released.
  • button
    copy link
    number
    required
    The index of the button used.
  • defaultPrevented
    copy link
    boolean
    required
    A read-only value indicating whether the default action was prevented.
  • endNanoseconds
    copy link
    number
    required
    The number of nanoseconds to add to endTime.
  • endTime
    copy link
    Date
    required
    The end of the time range covered by the targeted item. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
  • eventIds
    copy link
    string[]
    required
    An array of ids of events within the targeted item. Only defined if targetType is event, eventSummary or cell.
  • id
    copy link
    string | null
    required
    The id of the targeted item.
  • label
    copy link
    string
    required
    The label of the targeted item.
  • modifierKeys
    copy link
    EventModifierKeys
    required
    An object describing which modifier keys were pressed when the event occurred.
  • pointerId
    copy link
    number
    required
    The unique identifier of the pointer.
  • pointerType
    copy link
    string
    required
    The type of pointing device: mouse, touch or pen.
  • preventDefault()
    copy link
    If called, the default action is prevented.
    Parametersnone
    Returns
    void
  • startNanoseconds
    copy link
    number
    required
    The number of nanoseconds to add to startTime.
  • startTime
    copy link
    Date
    required
    The start of the time range covered by the targeted item. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
  • subItem
    copy link
    SubItem
    required
    An object containing details of the sub-item, or undefined if the cursor is not over a sub-item.
  • targetType
    copy link
    'annotationBody' | 'annotationDeleteButton' | 'annotationEditButton' | 'annotation' | 'cell' | 'entity' | 'entityGroup' | 'entityRun' | 'event' | 'eventSummary' | 'eventLabel' | 'focus' | 'fold' | 'glyph' | 'labelAreaBorder' | 'lensControl' | 'lensScrollbar' | 'pin' | 'scale' | 'timeSeriesChart' | null
    required
    The type of the targeted item.
  • time
    copy link
    Date
    required
    The timeline time corresponding to the pointer position. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
  • timeNanoseconds
    copy link
    number
    required
    The number of nanoseconds to add to time.
  • x
    copy link
    number
    required
    The distance from the left edge of the Timeline element to the pointer position.
  • y
    copy link
    number
    required
    The distance from the top edge of the Timeline element to the pointer position.

range

Fires when the time range shown in the timeline changes.
  • start
    copy link
    Date
    required
    The time at the start of the timeline after the range has changed as a Date in local time. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
  • startNanoseconds
    copy link
    number
    required
    The number of nanoseconds to add to the start time.
  • end
    copy link
    Date
    required
    The time at the end of the timeline after the range has changed as a Date in local time. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
  • endNanoseconds
    copy link
    number
    required
    The number of nanoseconds to add to the end time.
  • why
    copy link
    ChangeReason
    required
    The reason this event was fired:
    • 'auto' - The event was triggered by internal KronoGraph state.
    • 'user' - The event was triggered by user action.

selection-change

Beta
Fires when the list of selected events changes.
  • selection
    copy link
    string[]
    required
    The ids of the selected events.
  • why
    copy link
    ChangeReason
    required
    The reason this event was fired:
    • 'auto' - The event was triggered by internal KronoGraph state.
    • 'user' - The event was triggered by user action.

wheel

Fires continuously while the user is vertically or horizontally scrolling.
Default actions:
  • Vertical scrolling on the background - Zooms the timeline.
  • Vertical scrolling on the entity label area - Scrolls lens view up or down.
  • Horizontal scrolling - Pans the timeline.
  • defaultPrevented
    copy link
    boolean
    required
    A read-only value indicating whether the default action was prevented.
  • deltaMode
    copy link
    number
    required
    The unit of measurement for the delta value.
  • deltaX
    copy link
    number
    required
    The number of units that the wheel scrolled in the x direction.
  • deltaY
    copy link
    number
    required
    The number of units that the wheel scrolled in the y direction.
  • id
    copy link
    string | null
    required
    The id of the targeted item.
  • modifierKeys
    copy link
    EventModifierKeys
    required
    An object describing which modifier keys were pressed when the event occurred.
  • preventDefault()
    copy link
    If called, the default action is prevented.
    Parametersnone
    Returns
    void
  • targetType
    copy link
    'annotationBody' | 'annotationDeleteButton' | 'annotationEditButton' | 'annotation' | 'cell' | 'entity' | 'entityGroup' | 'entityRun' | 'event' | 'eventSummary' | 'eventLabel' | 'focus' | 'fold' | 'glyph' | 'labelAreaBorder' | 'lensControl' | 'lensScrollbar' | 'pin' | 'scale' | 'timeSeriesChart' | null
    required
    The type of the targeted item.
  • x
    copy link
    number
    required
    The distance from the left edge of the Timeline element to the pointer position.
  • y
    copy link
    number
    required
    The distance from the top edge of the Timeline element to the pointer position.

Timeline Props

You can control the state, appearance and behavior of the timeline by setting the props below.

The timeline also supports standard element props - including id, className, and interaction events (i.e., onClick).

annotations
copy link
object
Beta
A dictionary of annotations to be displayed in the timeline, where the keys are the annotation ids and the values are Annotation objects.
className
copy link
string
If the timeline receives a className it will not apply its default style. We recommend styling the timeline's parent element, rather than passing a className to the timeline itself.
entities
copy link
object
A dictionary of entities to be displayed in the timeline, where the keys are the entity ids and the values are Entity objects. Ids must be unique across both entities and events.
entityTypes
copy link
object
A dictionary of entity types, where the keys are the entity type names and the values are EntityType objects. May specify properties for the built-in 'default' entity type.
events
copy link
object
A dictionary of events to be displayed in the timeline, where the keys are the event ids and the values are Event objects. Ids must be unique across both entities and events.
eventTypes
copy link
object
A dictionary of event types, where the keys are the event type names and the values are EventType objects. May specify properties for the 'default' event type.
expandedRows
copy link
ExpandedRows
Beta
The entities to be expanded by adding sub-rows (where space allows) to space out overlapping events vertically. See Expanded Rows.
focus
copy link
string | string[]
The id or ids of the events or entities to focus on. When the timeline is focused, only focused items and their connections are shown. Focused events will keep the entities they are linked to in focus. Focusing does not affect time series charts.
highlight
copy link
string | string[]
The ids of the rows and entities to highlight. Highlighted entities and rows are drawn with a distinct highlightColor.
labelAreaWidth
copy link
LabelAreaWidth
Sets the mode of calculation for the width of the label area and the width, if the mode is fixed.
lens
copy link
string | null
The id of the entity at the center of the lens, or null if lens view is not open.
markers
copy link
Marker[]
The timeline markers drawn across the timeline at a specified time.
options
copy link
TimelineOptions
Defines options for the timeline.
ordering
copy link
'firstevent' | 'lastevent' | 'keyorder' | 'alphabetical' | 'shorteneventlines'default:'shorteneventlines'
The ordering of entity groups, and entities within a group:
  • 'alphabetical' - Order alphabetically by the first letter of the entity labels.
  • 'firstevent' - Order by the time of the first event associated with the entity.
  • 'lastevent' - Order by the time of the last event of each entity (ascending).
  • 'keyorder' - Order by the indices of the entities data object.
  • 'shorteneventlines' - Order to shorten the vertical event lines between entities.
pin
copy link
string[]
The ids of entities that are pinned.
range
copy link
TimeRange
The range of time shown in the timeline.
reveal
copy link
string | string[]
The ids of the events to reveal when the heatmap view is shown.
selection
copy link
string | string[]
Beta
The ids of the selected events. Selected events are drawn with a distinct selectionColor.
selectionMode
copy link
boolean
Beta
Whether the timeline is in selection mode.
style
copy link
CSSProperties
Standard styling properties for the element. We recommend styling the timeline's parent element, not the timeline itself. Default is:
{
   position: 'relative',
   height: '100%',
   minHeight: '100px',
   width: '100%',
}
timeSeriesCharts
copy link
object
A dictionary of time series charts, where the keys are the time series chart ids and the values are TimeSeriesChart objects. Ids must be unique.
timeSeriesChartStacks
copy link
object
A dictionary of time series chart stacks, where the keys are the time series chart stack ids and the values are TimeSeriesChartStack objects. Ids must be unique.

Handling Events

KronoGraph lets you respond to various events fired by the timeline, which can be triggered either by user interaction or by items changing in the timeline.

To attach an event handler to an event, pass your event handler functions through to the event props.

When an event is invoked, any attached handler functions are passed a single object containing all the details of the event.

To override the default behavior of an event, call the preventDefault() function in the event handler.

The timeline also supports standard element events, including onClick, onKeyDown, onFocus etc.

onTimelineChange(event)
copy link
Invoked whenever the timeline triggers a change of state.
Parameters
  • event
    copy link
    object
    An object with details of the event.
      • annotations
        copy link
        { [id: string]: Annotation }
        Beta
        required
        The current set of annotations.
      • focus
        copy link
        string[]
        required
        The ids of the focused entities.
      • expandedRows
        copy link
        { mode: 'auto' | 'manual'; expandedRowIds: string[] }
        required
        The mode and ids of the expanded entity rows.
      • highlight
        copy link
        string[]
        required
        The ids of the highlighted entities.
      • lens
        copy link
        string | null
        required
        The id of the entity at the center of the lens.
      • pin
        copy link
        string[]
        required
        The ids of the pinned entities.
      • range
        copy link
        { start: Date; startNanoseconds: number; end: Date; endNanoseconds: number }
        required
        An object containing the range of visible times.
      • selection
        copy link
        string[]
        required
        The ids of the selected events.
      • why
        copy link
        ChangeReason
        required
        The reason this event was fired:
        • 'auto' - The event was triggered by internal KronoGraph state.
        • 'user' - The event was triggered by user action.
Returns
void
onTimelineClick(event)
copy link
Invoked when the user clicks or taps on the timeline.
Default actions on the item controls :
  • Focus control - Focuses or unfocuses the entity row.
  • Pin control - Pins or unpins the entity row.
  • Annotation delete control - Deletes the annotation.
Parameters
  • event
    copy link
    object
    An object with details of the event.
      • button
        copy link
        number
        required
        The index of the button used.
      • defaultPrevented
        copy link
        boolean
        required
        A read-only value indicating whether the default action was prevented.
      • endNanoseconds
        copy link
        number
        required
        The number of nanoseconds to add to endTime.
      • endTime
        copy link
        Date
        required
        The end of the time range covered by the targeted item. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
      • entitiesInRow
        copy link
        object
        required
        If the event targets an entity row, a dictionary object containing the entities in the row, indexed by the entity ids.
      • eventIds
        copy link
        string[]
        required
        An array of ids of events within the targeted item. Only defined if targetType is event, eventSummary or cell.
      • id
        copy link
        string | null
        required
        The id of the targeted item.
      • label
        copy link
        string
        required
        The label of the targeted item.
      • modifierKeys
        copy link
        EventModifierKeys
        required
        An object describing which modifier keys were pressed when the event occurred.
      • pointerId
        copy link
        number
        required
        The unique identifier of the pointer.
      • pointerType
        copy link
        string
        required
        The type of pointing device: mouse, touch or pen.
      • preventDefault()
        copy link
        If called, the default action is prevented.
        Parametersnone
        Returns
        void
      • startNanoseconds
        copy link
        number
        required
        The number of nanoseconds to add to startTime.
      • startTime
        copy link
        Date
        required
        The start of the time range covered by the targeted item. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
      • subItem
        copy link
        SubItem
        required
        An object containing details of the sub-item, or undefined if the cursor is not over a sub-item.
      • targetType
        copy link
        'annotationBody' | 'annotationDeleteButton' | 'annotationEditButton' | 'annotation' | 'cell' | 'entity' | 'entityGroup' | 'entityRun' | 'event' | 'eventSummary' | 'eventLabel' | 'focus' | 'fold' | 'glyph' | 'labelAreaBorder' | 'lensControl' | 'lensScrollbar' | 'pin' | 'scale' | 'timeSeriesChart' | null
        required
        The type of the targeted item.
      • time
        copy link
        Date
        required
        The timeline time corresponding to the pointer position. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
      • timeNanoseconds
        copy link
        number
        required
        The number of nanoseconds to add to time.
      • x
        copy link
        number
        required
        The distance from the left edge of the Timeline element to the pointer position.
      • y
        copy link
        number
        required
        The distance from the top edge of the Timeline element to the pointer position.
Returns
void
onTimelineDraw()
copy link
Invoked whenever the timeline is drawn.
Parametersnone
Returns
void
onTimelineContextMenu(event)
copy link
Invoked on a right click or a long press on the timeline.
Default action:
  • Suppresses the click event.
Parameters
  • event
    copy link
    object
    An object with details of the event.
      • button
        copy link
        number
        required
        The index of the button used.
      • defaultPrevented
        copy link
        boolean
        required
        A read-only value indicating whether the default action was prevented.
      • endNanoseconds
        copy link
        number
        required
        The number of nanoseconds to add to endTime.
      • endTime
        copy link
        Date
        required
        The end of the time range covered by the targeted item. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
      • entitiesInRow
        copy link
        object
        required
        If the event targets an entity row, a dictionary object containing the entities in the row, indexed by the entity ids.
      • eventIds
        copy link
        string[]
        required
        An array of ids of events within the targeted item. Only defined if targetType is event, eventSummary or cell.
      • id
        copy link
        string | null
        required
        The id of the targeted item.
      • label
        copy link
        string
        required
        The label of the targeted item.
      • modifierKeys
        copy link
        EventModifierKeys
        required
        An object describing which modifier keys were pressed when the event occurred.
      • pointerId
        copy link
        number
        required
        The unique identifier of the pointer.
      • pointerType
        copy link
        string
        required
        The type of pointing device: mouse, touch or pen.
      • preventDefault()
        copy link
        If called, the default action is prevented.
        Parametersnone
        Returns
        void
      • startNanoseconds
        copy link
        number
        required
        The number of nanoseconds to add to startTime.
      • startTime
        copy link
        Date
        required
        The start of the time range covered by the targeted item. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
      • subItem
        copy link
        SubItem
        required
        An object containing details of the sub-item, or undefined if the cursor is not over a sub-item.
      • targetType
        copy link
        'annotationBody' | 'annotationDeleteButton' | 'annotationEditButton' | 'annotation' | 'cell' | 'entity' | 'entityGroup' | 'entityRun' | 'event' | 'eventSummary' | 'eventLabel' | 'focus' | 'fold' | 'glyph' | 'labelAreaBorder' | 'lensControl' | 'lensScrollbar' | 'pin' | 'scale' | 'timeSeriesChart' | null
        required
        The type of the targeted item.
      • time
        copy link
        Date
        required
        The timeline time corresponding to the pointer position. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
      • timeNanoseconds
        copy link
        number
        required
        The number of nanoseconds to add to time.
      • x
        copy link
        number
        required
        The distance from the left edge of the Timeline element to the pointer position.
      • y
        copy link
        number
        required
        The distance from the top edge of the Timeline element to the pointer position.
Returns
void
onTimelineDoubleClick(event)
copy link
Invoked on a double-click or a double-tap on the timeline.
Default actions:
  • On the background - Unfocuses any focused entity rows.
  • On an entity row - Focuses or unfocuses the entity row.
  • On the scale - Sets the timeline range to the startTime and endTime properties of the selected scale item.
Parameters
  • event
    copy link
    object
    An object with details of the event.
      • button
        copy link
        number
        required
        The index of the button used.
      • defaultPrevented
        copy link
        boolean
        required
        A read-only value indicating whether the default action was prevented.
      • endNanoseconds
        copy link
        number
        required
        The number of nanoseconds to add to endTime.
      • endTime
        copy link
        Date
        required
        The end of the time range covered by the targeted item. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
      • entitiesInRow
        copy link
        object
        required
        If the event targets an entity row, a dictionary object containing the entities in the row, indexed by the entity ids.
      • eventIds
        copy link
        string[]
        required
        An array of ids of events within the targeted item. Only defined if targetType is event, eventSummary or cell.
      • id
        copy link
        string | null
        required
        The id of the targeted item.
      • label
        copy link
        string
        required
        The label of the targeted item.
      • modifierKeys
        copy link
        EventModifierKeys
        required
        An object describing which modifier keys were pressed when the event occurred.
      • pointerId
        copy link
        number
        required
        The unique identifier of the pointer.
      • pointerType
        copy link
        string
        required
        The type of pointing device: mouse, touch or pen.
      • preventDefault()
        copy link
        If called, the default action is prevented.
        Parametersnone
        Returns
        void
      • startNanoseconds
        copy link
        number
        required
        The number of nanoseconds to add to startTime.
      • startTime
        copy link
        Date
        required
        The start of the time range covered by the targeted item. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
      • subItem
        copy link
        SubItem
        required
        An object containing details of the sub-item, or undefined if the cursor is not over a sub-item.
      • targetType
        copy link
        'annotationBody' | 'annotationDeleteButton' | 'annotationEditButton' | 'annotation' | 'cell' | 'entity' | 'entityGroup' | 'entityRun' | 'event' | 'eventSummary' | 'eventLabel' | 'focus' | 'fold' | 'glyph' | 'labelAreaBorder' | 'lensControl' | 'lensScrollbar' | 'pin' | 'scale' | 'timeSeriesChart' | null
        required
        The type of the targeted item.
      • time
        copy link
        Date
        required
        The timeline time corresponding to the pointer position. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
      • timeNanoseconds
        copy link
        number
        required
        The number of nanoseconds to add to time.
      • x
        copy link
        number
        required
        The distance from the left edge of the Timeline element to the pointer position.
      • y
        copy link
        number
        required
        The distance from the top edge of the Timeline element to the pointer position.
Returns
void
onTimelineDragEnd(event)
copy link
Invoked when the drag is finished and pointer is released, or when the drag is canceled. On touch devices this fires when the finger or pointing device is lifted.
Default action:
  • On MarqueeRange drag type - the timeline will zoom into the selected range.
Parameters
  • event
    copy link
    object
    An object with details of the event.
      • button
        copy link
        number
        required
        The index of the button used.
      • defaultPrevented
        copy link
        boolean
        required
        A read-only value indicating whether the default action was prevented.
      • dragType
        copy link
        'annotationScrollBar' | 'labelAreaWidth' | 'lensScrollbar' | 'marqueeRange' | 'marqueeSelection' | 'moveAnnotation' | 'pan' | null
        required
        The type of drag.
      • endNanoseconds
        copy link
        number
        required
        The number of nanoseconds to add to endTime.
      • endTime
        copy link
        Date
        required
        The end of the time range covered by the targeted item. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
      • entitiesInRow
        copy link
        object
        required
        If the event targets an entity row, a dictionary object containing the entities in the row, indexed by the entity ids.
      • entityRangeSubject
        copy link
        EntityRangeSubject
        required
        The entity range within the dragged area. Only present when dragType is 'marqueeSelection'.
      • eventIds
        copy link
        string[]
        required
        An array of ids of events within the targeted item. Only defined if targetType is event, eventSummary or cell.
      • id
        copy link
        string | null
        required
        The id of the targeted item.
      • label
        copy link
        string
        required
        The label of the targeted item.
      • modifierKeys
        copy link
        EventModifierKeys
        required
        An object describing which modifier keys were pressed when the event occurred.
      • pointerId
        copy link
        number
        required
        The unique identifier of the pointer.
      • pointerType
        copy link
        string
        required
        The type of pointing device: mouse, touch or pen.
      • preventDefault()
        copy link
        If called, the default action is prevented.
        Parametersnone
        Returns
        void
      • startNanoseconds
        copy link
        number
        required
        The number of nanoseconds to add to startTime.
      • startTime
        copy link
        Date
        required
        The start of the time range covered by the targeted item. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
      • subItem
        copy link
        SubItem
        required
        An object containing details of the sub-item, or undefined if the cursor is not over a sub-item.
      • targetType
        copy link
        'annotationBody' | 'annotationDeleteButton' | 'annotationEditButton' | 'annotation' | 'cell' | 'entity' | 'entityGroup' | 'entityRun' | 'event' | 'eventSummary' | 'eventLabel' | 'focus' | 'fold' | 'glyph' | 'labelAreaBorder' | 'lensControl' | 'lensScrollbar' | 'pin' | 'scale' | 'timeSeriesChart' | null
        required
        The type of the targeted item.
      • time
        copy link
        Date
        required
        The timeline time corresponding to the pointer position. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
      • timeNanoseconds
        copy link
        number
        required
        The number of nanoseconds to add to time.
      • x
        copy link
        number
        required
        The distance from the left edge of the Timeline element to the pointer position.
      • y
        copy link
        number
        required
        The distance from the top edge of the Timeline element to the pointer position.
Returns
void
onTimelineDragMove(event)
copy link
Invoked continuously as the cursor moves during a drag.
Parameters
  • event
    copy link
    object
    An object with details of the event.
      • button
        copy link
        number
        required
        The index of the button used.
      • defaultPrevented
        copy link
        boolean
        required
        A read-only value indicating whether the default action was prevented.
      • dragType
        copy link
        'annotationScrollBar' | 'labelAreaWidth' | 'lensScrollbar' | 'marqueeRange' | 'marqueeSelection' | 'moveAnnotation' | 'pan' | null
        required
        The type of drag.
      • endNanoseconds
        copy link
        number
        required
        The number of nanoseconds to add to endTime.
      • endTime
        copy link
        Date
        required
        The end of the time range covered by the targeted item. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
      • entitiesInRow
        copy link
        object
        required
        If the event targets an entity row, a dictionary object containing the entities in the row, indexed by the entity ids.
      • eventIds
        copy link
        string[]
        required
        An array of ids of events within the targeted item. Only defined if targetType is event, eventSummary or cell.
      • id
        copy link
        string | null
        required
        The id of the targeted item.
      • label
        copy link
        string
        required
        The label of the targeted item.
      • modifierKeys
        copy link
        EventModifierKeys
        required
        An object describing which modifier keys were pressed when the event occurred.
      • pointerId
        copy link
        number
        required
        The unique identifier of the pointer.
      • pointerType
        copy link
        string
        required
        The type of pointing device: mouse, touch or pen.
      • preventDefault()
        copy link
        If called, the default action is prevented.
        Parametersnone
        Returns
        void
      • startNanoseconds
        copy link
        number
        required
        The number of nanoseconds to add to startTime.
      • startTime
        copy link
        Date
        required
        The start of the time range covered by the targeted item. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
      • subItem
        copy link
        SubItem
        required
        An object containing details of the sub-item, or undefined if the cursor is not over a sub-item.
      • targetType
        copy link
        'annotationBody' | 'annotationDeleteButton' | 'annotationEditButton' | 'annotation' | 'cell' | 'entity' | 'entityGroup' | 'entityRun' | 'event' | 'eventSummary' | 'eventLabel' | 'focus' | 'fold' | 'glyph' | 'labelAreaBorder' | 'lensControl' | 'lensScrollbar' | 'pin' | 'scale' | 'timeSeriesChart' | null
        required
        The type of the targeted item.
      • time
        copy link
        Date
        required
        The timeline time corresponding to the pointer position. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
      • timeNanoseconds
        copy link
        number
        required
        The number of nanoseconds to add to time.
      • x
        copy link
        number
        required
        The distance from the left edge of the Timeline element to the pointer position.
      • y
        copy link
        number
        required
        The distance from the top edge of the Timeline element to the pointer position.
Returns
void
onTimelineDragStart(event)
copy link
Invoked when a drag is started. Use setDragOptions to set the dragging behavior.
Default actions:
  • On the background - Pans the timeline.
  • On the scale - Draws a marquee range. On drag-end, the default action is to zoom into the selected range.
  • On the label area border - Adjusts the label area width.
Parameters
  • event
    copy link
    object
    An object with details of the event.
      • button
        copy link
        number
        required
        The index of the button used.
      • defaultPrevented
        copy link
        boolean
        required
        A read-only value indicating whether the default action was prevented.
      • dragType
        copy link
        'annotationScrollBar' | 'labelAreaWidth' | 'lensScrollbar' | 'marqueeRange' | 'marqueeSelection' | 'moveAnnotation' | 'pan' | null
        required
        The type of drag.
      • endNanoseconds
        copy link
        number
        required
        The number of nanoseconds to add to endTime.
      • endTime
        copy link
        Date
        required
        The end of the time range covered by the targeted item. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
      • entitiesInRow
        copy link
        object
        required
        If the event targets an entity row, a dictionary object containing the entities in the row, indexed by the entity ids.
      • eventIds
        copy link
        string[]
        required
        An array of ids of events within the targeted item. Only defined if targetType is event, eventSummary or cell.
      • id
        copy link
        string | null
        required
        The id of the targeted item.
      • label
        copy link
        string
        required
        The label of the targeted item.
      • modifierKeys
        copy link
        EventModifierKeys
        required
        An object describing which modifier keys were pressed when the event occurred.
      • pointerId
        copy link
        number
        required
        The unique identifier of the pointer.
      • pointerType
        copy link
        string
        required
        The type of pointing device: mouse, touch or pen.
      • preventDefault()
        copy link
        If called, the default action is prevented.
        Parametersnone
        Returns
        void
      • setDragOptions(options)
        copy link
        Controls the dragging behavior.
        Parameters
        • options
          copy link
          DraggerOptions
          required
          Options to control the dragging behavior.
        Returns
        void
      • startNanoseconds
        copy link
        number
        required
        The number of nanoseconds to add to startTime.
      • startTime
        copy link
        Date
        required
        The start of the time range covered by the targeted item. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
      • subItem
        copy link
        SubItem
        required
        An object containing details of the sub-item, or undefined if the cursor is not over a sub-item.
      • targetType
        copy link
        'annotationBody' | 'annotationDeleteButton' | 'annotationEditButton' | 'annotation' | 'cell' | 'entity' | 'entityGroup' | 'entityRun' | 'event' | 'eventSummary' | 'eventLabel' | 'focus' | 'fold' | 'glyph' | 'labelAreaBorder' | 'lensControl' | 'lensScrollbar' | 'pin' | 'scale' | 'timeSeriesChart' | null
        required
        The type of the targeted item.
      • time
        copy link
        Date
        required
        The timeline time corresponding to the pointer position. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
      • timeNanoseconds
        copy link
        number
        required
        The number of nanoseconds to add to time.
      • x
        copy link
        number
        required
        The distance from the left edge of the Timeline element to the pointer position.
      • y
        copy link
        number
        required
        The distance from the top edge of the Timeline element to the pointer position.
Returns
void
onTimelineHover(event)
copy link
Invoked when the user hovers over an item for a specified time. The delay is defined by the hover option.
Parameters
  • event
    copy link
    object
    An object with details of the event.
      • button
        copy link
        number
        required
        The index of the button used.
      • defaultPrevented
        copy link
        boolean
        required
        A read-only value indicating whether the default action was prevented.
      • endNanoseconds
        copy link
        number
        required
        The number of nanoseconds to add to endTime.
      • endTime
        copy link
        Date
        required
        The end of the time range covered by the targeted item. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
      • entitiesInRow
        copy link
        object
        required
        If the event targets an entity row, a dictionary object containing the entities in the row, indexed by the entity ids.
      • eventIds
        copy link
        string[]
        required
        An array of ids of events within the targeted item. Only defined if targetType is event, eventSummary or cell.
      • id
        copy link
        string | null
        required
        The id of the targeted item.
      • label
        copy link
        string
        required
        The label of the targeted item.
      • modifierKeys
        copy link
        EventModifierKeys
        required
        An object describing which modifier keys were pressed when the event occurred.
      • pointerId
        copy link
        number
        required
        The unique identifier of the pointer.
      • pointerType
        copy link
        string
        required
        The type of pointing device: mouse, touch or pen.
      • preventDefault()
        copy link
        If called, the default action is prevented.
        Parametersnone
        Returns
        void
      • startNanoseconds
        copy link
        number
        required
        The number of nanoseconds to add to startTime.
      • startTime
        copy link
        Date
        required
        The start of the time range covered by the targeted item. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
      • subItem
        copy link
        SubItem
        required
        An object containing details of the sub-item, or undefined if the cursor is not over a sub-item.
      • targetType
        copy link
        'annotationBody' | 'annotationDeleteButton' | 'annotationEditButton' | 'annotation' | 'cell' | 'entity' | 'entityGroup' | 'entityRun' | 'event' | 'eventSummary' | 'eventLabel' | 'focus' | 'fold' | 'glyph' | 'labelAreaBorder' | 'lensControl' | 'lensScrollbar' | 'pin' | 'scale' | 'timeSeriesChart' | null
        required
        The type of the targeted item.
      • time
        copy link
        Date
        required
        The timeline time corresponding to the pointer position. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
      • timeNanoseconds
        copy link
        number
        required
        The number of nanoseconds to add to time.
      • x
        copy link
        number
        required
        The distance from the left edge of the Timeline element to the pointer position.
      • y
        copy link
        number
        required
        The distance from the top edge of the Timeline element to the pointer position.
Returns
void
onTimelineKeyDown(event)
copy link
Invoked when the user presses a key.
Parameters
  • event
    copy link
    object
    An object with details of the event.
      • keyCode
        copy link
        number
        required
        The keyCode of the key pressed.
      • defaultPrevented
        copy link
        boolean
        required
        A read-only value indicating whether the default action was prevented.
      • modifierKeys
        copy link
        EventModifierKeys
        required
        An object describing which modifier keys were pressed when the event occurred.
Returns
void
onTimelineKeyUp(event)
copy link
Invoked when the user releases a key.
Parameters
  • event
    copy link
    object
    An object with details of the event.
      • keyCode
        copy link
        number
        required
        The keyCode of the key pressed.
      • defaultPrevented
        copy link
        boolean
        required
        A read-only value indicating whether the default action was prevented.
      • modifierKeys
        copy link
        EventModifierKeys
        required
        An object describing which modifier keys were pressed when the event occurred.
Returns
void
onTimelinePointerDown(event)
copy link
Invoked when a pointer presses down on the timeline.
Parameters
  • event
    copy link
    object
    An object with details of the event.
      • button
        copy link
        number
        required
        The index of the button used.
      • defaultPrevented
        copy link
        boolean
        required
        A read-only value indicating whether the default action was prevented.
      • endNanoseconds
        copy link
        number
        required
        The number of nanoseconds to add to endTime.
      • endTime
        copy link
        Date
        required
        The end of the time range covered by the targeted item. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
      • entitiesInRow
        copy link
        object
        required
        If the event targets an entity row, a dictionary object containing the entities in the row, indexed by the entity ids.
      • eventIds
        copy link
        string[]
        required
        An array of ids of events within the targeted item. Only defined if targetType is event, eventSummary or cell.
      • id
        copy link
        string | null
        required
        The id of the targeted item.
      • label
        copy link
        string
        required
        The label of the targeted item.
      • modifierKeys
        copy link
        EventModifierKeys
        required
        An object describing which modifier keys were pressed when the event occurred.
      • pointerId
        copy link
        number
        required
        The unique identifier of the pointer.
      • pointerType
        copy link
        string
        required
        The type of pointing device: mouse, touch or pen.
      • preventDefault()
        copy link
        If called, the default action is prevented.
        Parametersnone
        Returns
        void
      • startNanoseconds
        copy link
        number
        required
        The number of nanoseconds to add to startTime.
      • startTime
        copy link
        Date
        required
        The start of the time range covered by the targeted item. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
      • subItem
        copy link
        SubItem
        required
        An object containing details of the sub-item, or undefined if the cursor is not over a sub-item.
      • targetType
        copy link
        'annotationBody' | 'annotationDeleteButton' | 'annotationEditButton' | 'annotation' | 'cell' | 'entity' | 'entityGroup' | 'entityRun' | 'event' | 'eventSummary' | 'eventLabel' | 'focus' | 'fold' | 'glyph' | 'labelAreaBorder' | 'lensControl' | 'lensScrollbar' | 'pin' | 'scale' | 'timeSeriesChart' | null
        required
        The type of the targeted item.
      • time
        copy link
        Date
        required
        The timeline time corresponding to the pointer position. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
      • timeNanoseconds
        copy link
        number
        required
        The number of nanoseconds to add to time.
      • x
        copy link
        number
        required
        The distance from the left edge of the Timeline element to the pointer position.
      • y
        copy link
        number
        required
        The distance from the top edge of the Timeline element to the pointer position.
Returns
void
onTimelinePointerMove(event)
copy link
Invoked continuously as the pointer moves on the timeline, or the timeline moves beneath the pointer.
Default action:
  • On an entity row - Highlights the entity row and displays available controls (pin or focus).
  • On a time series chart - Highlights the nearest data point.
Parameters
  • event
    copy link
    object
    An object with details of the event.
      • button
        copy link
        number
        required
        The index of the button used.
      • defaultPrevented
        copy link
        boolean
        required
        A read-only value indicating whether the default action was prevented.
      • endNanoseconds
        copy link
        number
        required
        The number of nanoseconds to add to endTime.
      • endTime
        copy link
        Date
        required
        The end of the time range covered by the targeted item. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
      • entitiesInRow
        copy link
        object
        required
        If the event targets an entity row, a dictionary object containing the entities in the row, indexed by the entity ids.
      • eventIds
        copy link
        string[]
        required
        An array of ids of events within the targeted item. Only defined if targetType is event, eventSummary or cell.
      • id
        copy link
        string | null
        required
        The id of the targeted item.
      • label
        copy link
        string
        required
        The label of the targeted item.
      • modifierKeys
        copy link
        EventModifierKeys
        required
        An object describing which modifier keys were pressed when the event occurred.
      • pointerId
        copy link
        number
        required
        The unique identifier of the pointer.
      • pointerType
        copy link
        string
        required
        The type of pointing device: mouse, touch or pen.
      • preventDefault()
        copy link
        If called, the default action is prevented.
        Parametersnone
        Returns
        void
      • startNanoseconds
        copy link
        number
        required
        The number of nanoseconds to add to startTime.
      • startTime
        copy link
        Date
        required
        The start of the time range covered by the targeted item. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
      • subItem
        copy link
        SubItem
        required
        An object containing details of the sub-item, or undefined if the cursor is not over a sub-item.
      • targetType
        copy link
        'annotationBody' | 'annotationDeleteButton' | 'annotationEditButton' | 'annotation' | 'cell' | 'entity' | 'entityGroup' | 'entityRun' | 'event' | 'eventSummary' | 'eventLabel' | 'focus' | 'fold' | 'glyph' | 'labelAreaBorder' | 'lensControl' | 'lensScrollbar' | 'pin' | 'scale' | 'timeSeriesChart' | null
        required
        The type of the targeted item.
      • time
        copy link
        Date
        required
        The timeline time corresponding to the pointer position. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
      • timeNanoseconds
        copy link
        number
        required
        The number of nanoseconds to add to time.
      • x
        copy link
        number
        required
        The distance from the left edge of the Timeline element to the pointer position.
      • y
        copy link
        number
        required
        The distance from the top edge of the Timeline element to the pointer position.
Returns
void
onTimelinePointerUp(event)
copy link
Invoked when the pointer is released.
Parameters
  • event
    copy link
    object
    An object with details of the event.
      • button
        copy link
        number
        required
        The index of the button used.
      • defaultPrevented
        copy link
        boolean
        required
        A read-only value indicating whether the default action was prevented.
      • endNanoseconds
        copy link
        number
        required
        The number of nanoseconds to add to endTime.
      • endTime
        copy link
        Date
        required
        The end of the time range covered by the targeted item. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
      • entitiesInRow
        copy link
        object
        required
        If the event targets an entity row, a dictionary object containing the entities in the row, indexed by the entity ids.
      • eventIds
        copy link
        string[]
        required
        An array of ids of events within the targeted item. Only defined if targetType is event, eventSummary or cell.
      • id
        copy link
        string | null
        required
        The id of the targeted item.
      • label
        copy link
        string
        required
        The label of the targeted item.
      • modifierKeys
        copy link
        EventModifierKeys
        required
        An object describing which modifier keys were pressed when the event occurred.
      • pointerId
        copy link
        number
        required
        The unique identifier of the pointer.
      • pointerType
        copy link
        string
        required
        The type of pointing device: mouse, touch or pen.
      • preventDefault()
        copy link
        If called, the default action is prevented.
        Parametersnone
        Returns
        void
      • startNanoseconds
        copy link
        number
        required
        The number of nanoseconds to add to startTime.
      • startTime
        copy link
        Date
        required
        The start of the time range covered by the targeted item. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
      • subItem
        copy link
        SubItem
        required
        An object containing details of the sub-item, or undefined if the cursor is not over a sub-item.
      • targetType
        copy link
        'annotationBody' | 'annotationDeleteButton' | 'annotationEditButton' | 'annotation' | 'cell' | 'entity' | 'entityGroup' | 'entityRun' | 'event' | 'eventSummary' | 'eventLabel' | 'focus' | 'fold' | 'glyph' | 'labelAreaBorder' | 'lensControl' | 'lensScrollbar' | 'pin' | 'scale' | 'timeSeriesChart' | null
        required
        The type of the targeted item.
      • time
        copy link
        Date
        required
        The timeline time corresponding to the pointer position. When the scale is wrapped, this is relative to the base range - see Scale Wrapping.
      • timeNanoseconds
        copy link
        number
        required
        The number of nanoseconds to add to time.
      • x
        copy link
        number
        required
        The distance from the left edge of the Timeline element to the pointer position.
      • y
        copy link
        number
        required
        The distance from the top edge of the Timeline element to the pointer position.
Returns
void
onTimelineWheel(event)
copy link
Invoked continuously while the user is vertically or horizontally scrolling.
Default actions:
  • Vertical scrolling on the background - Zooms the timeline.
  • Vertical scrolling on the lens - Scrolls the lens up or down.
  • Horizontal scrolling - Pans the timeline.
Parameters
  • event
    copy link
    object
    An object with details of the event.
      • deltaMode
        copy link
        number
        required
        The unit of measurement for the delta value.
      • defaultPrevented
        copy link
        boolean
        required
        A read-only value indicating whether the default action was prevented.
      • deltaX
        copy link
        number
        required
        The number of units that the wheel scrolled in the x direction.
      • deltaY
        copy link
        number
        required
        The number of units that the wheel scrolled in the y direction.
      • id
        copy link
        string | null
        required
        The id of the targeted item.
      • modifierKeys
        copy link
        EventModifierKeys
        required
        An object describing which modifier keys were pressed when the event occurred.
      • targetType
        copy link
        'annotationBody' | 'annotationDeleteButton' | 'annotationEditButton' | 'annotation' | 'cell' | 'entity' | 'entityGroup' | 'entityRun' | 'event' | 'eventSummary' | 'eventLabel' | 'focus' | 'fold' | 'glyph' | 'labelAreaBorder' | 'lensControl' | 'lensScrollbar' | 'pin' | 'scale' | 'timeSeriesChart' | null
        required
        The type of the targeted item.
      • x
        copy link
        number
        required
        The distance from the left edge of the Timeline element to the pointer position.
      • y
        copy link
        number
        required
        The distance from the top edge of the Timeline element to the pointer position.
Returns
void

Timeline Instance Methods

Timeline instance methods are used to update the view.

Use ref to call methods on an instance of a timeline.

expandedRows()
copy link
Beta
Expands entities by adding sub-rows to space out events vertically, see Expanded Rows.
Parametersnone
Returns
ExpandedRows
An object containing the ids of the entities to be expanded and the mode used to determine them.
export(options)
copy link
Exports a static image of the timeline. The exported image is encoded in a blob URL.
Parameters
  • options
    copy link
    ExportOptions
    required
    Options related to producing an export of the current view.
      • includeAnnotations
        booleandefault:true
        Whether to include annotations in the output.
      • type
        'png'
        required
        The file type of the output.
Returns
Promise<ExportResult>
A promise that will resolve with an object containing the blob URL of the exported image or reject with an error.
fit()
copy link
Fits all the events and time series chart data points in the active range into the viewport. If Scale Wrapping is used, fits the wrapped time range into the viewport.
Parametersnone
Returns
void
getAnnotationBodyPosition(annotationId)
copy link
Beta
Gets an object describing the position of an annotation's body.
Parameters
  • annotationId
    copy link
    string
    required
    The id of the annotation.
Returns
AnnotationBodyPosition | null
An AnnotationBodyPosition object, or null if the annotation is not shown in the timeline.
getEntityPosition(entityId)
copy link
Gets an object describing the position of an entity.
Parameters
  • entityId
    copy link
    string
    required
    The id of the entity.
Returns
EntityPosition | null
An EntityPosition object, or null if the entity is not shown in the timeline.
getEventPosition(eventId)
copy link
Gets an object describing the position of an event.
Parameters
  • eventId
    copy link
    string
    required
    The id of the event.
Returns
EventPosition | null
An EventPosition object, or null if the event is not in the current timeline range.
getInRangeItems(options)
copy link
Returns an object detailing the ids of events and entities that are in the current range.
Parameters
  • options
    copy link
    object
    Specifies which items are included.
      • focus
        booleandefault:true
        If there is an entity that is focused, then this option defines whether to include just the focused entity and its neighbors. Otherwise all events and entities in the current range are included.
Returns
{ entities: Object, events: Object }
Objects whose keys are the ids of entities and events in the current range.
isHeatmapShown()
copy link
Determines whether the heatmap is currently shown.
Parametersnone
Returns
boolean
True if the heatmap is currently shown, otherwise false.
labelAreaWidth()
copy link
Returns an object detailing the mode of calculation for the width of the label area and the width.
Parametersnone
Returns
LabelAreaWidth
An object containing the mode of calculation for the width of the label area and the width.
pan(direction, amount)
copy link
Pans the timeline in the specified direction. The panning range is limited and depends on the timeline data.
Parameters
  • direction
    copy link
    'left' | 'right'
    required
  • amount
    copy link
    numberdefault:0.3
    How far to pan the timeline. The distance is measured as a proportion of space across the visible timeline range.
Returns
void
ping(id, options)
copy link
Adds an animated effect to a specified event, and then removes it again.
Parameters
  • id
    copy link
    string | string[]
    required
    The id or ids of the events to ping.
  • options
    copy link
    object
    Options to control the animation.
      • color
        stringdefault:'#909090'
        The color to use for the animated effect.
      • mode
        'individual' | 'grouped'default:'individual'
        Whether the specified events should each have their own ping animation, or all events have a single outer ping animation.
      • repeat
        numberdefault:1
        The number of times the animation should be repeated.
      • spread
        numberdefault:42
        The distance between the start and the end of the ping stroke, in pixels.
      • strokeWidth
        numberdefault:12
        The width of the ping stroke at the end of the animation, in pixels.
      • time
        numberdefault:800
        The time the animation should take, in milliseconds.
Returns
void
zoom(direction)
copy link
Zoom the timeline in the manner specified. The zooming range is limited and depends on the timeline data.
Parameters
  • direction
    copy link
    'in' | 'out'
    required
Returns
void

Timeline Options

You can set various options and defaults on the timeline by passing an object to the options() function.

You can set various options and defaults on the timeline by setting the options Prop.

The options() function The options prop accepts an object with the following properties:

annotations
copy link
object
Beta
Options relating to annotations.
    • arrangeInRails
      copy link
      'auto' | 'off'default:'auto'
      Whether annotations are automatically arranged in rails to reduce overlaps.
    • bottomRailHeight
      copy link
      numberdefault:120
      The height of the bottom annotation rail.
    • maximumBodyHeight
      copy link
      numberdefault:160
      The maximum height of the annotation body.
    • maximumBodyWidth
      copy link
      numberdefault:280
      The maximum width of the annotation body.
    • showRails
      copy link
      'always' | 'auto'default:'auto'
      Whether rails are always shown, or appear automatically when there are annotations.
    • topRailHeight
      copy link
      numberdefault:120
      The height of the top annotation rail.
backgroundColor
copy link
stringdefault:'#242c32'
The color of the timeline background.
controls
copy link
object
Options relating to row controls.
    • deleteAnnotation
      copy link
      object
      Beta
      Options for the delete control on annotations.
        • backgroundColor
          copy link
          stringdefault:'#3e414b'
          The background color for the control.
        • color
          copy link
          stringdefault:'#afafaf'
          The color for the control.
        • hoverBackgroundColor
          copy link
          stringdefault:'#787c8e'
          The background color for the control when hovered.
        • hoverColor
          copy link
          stringdefault:'#ffffff'
          The color for the control when hovered.
        • show
          copy link
          booleandefault:true
          Whether to show the control.
    • editAnnotation
      copy link
      object
      Beta
      Options for the edit control on annotations.
        • backgroundColor
          copy link
          stringdefault:'#3e414b'
          The background color for the control.
        • color
          copy link
          stringdefault:'#afafaf'
          The color for the control.
        • hoverBackgroundColor
          copy link
          stringdefault:'#787c8e'
          The background color for the control when hovered.
        • hoverColor
          copy link
          stringdefault:'#ffffff'
          The color for the control when hovered.
        • show
          copy link
          booleandefault:false
          Whether to show the control.
    • focus
      copy link
      object
      Options for the focus control on entity rows.
        • show
          copy link
          booleandefault:true
          Whether to show the control.
    • pin
      copy link
      object
      Options for the pin control on entity rows.
        • show
          copy link
          booleandefault:true
          Whether to show the control.
entities
copy link
object
Options relating to entities.
    • glyphPosition
      copy link
      'left' | 'right'default:'left'
      The position of the glyph.
    • labelBackgroundColor
      copy link
      string | nulldefault:null
      The color to use for the background of entity labels. If null, backgroundColor is used.
    • showLines
      copy link
      'always' | 'individualEvents' | 'never'default:'individualEvents'
      Controls when to show entity lines:
      • 'always' - Always show entity lines.
      • 'individualEvents' - Show entity lines with individual events only, not with the heatmap.
      • 'never' - Never show entity lines.
    • standardRowHeight
      copy link
      numberdefault:24
      Standard height of entity rows in px, with a minimum value of 14.
    • truncateLabelsAt
      copy link
      numberdefault:40
      The number of characters to truncate entity labels at. Set to 0 to disable truncation. Only applies when the entity label area width mode is set to auto.
events
copy link
object
Options relating to events.
    • heatmapColor
      copy link
      null | string | string[] | HeatmapColorStep [] | HeatmapEventTypePriority []default:null
      The color to apply to the heatmap:
      • null - Cells use the average color of their underlying events, with an alpha applied based on the cell's value.
      • string - All cells will use the color specified, with an alpha applied based on the cell's value.
      • string[] - The array of colors specified will be used to assign colors based on each cell's value within the distribution of the cells in the visible range.
      • heatmapColorStep[] - Colors are assigned to cells based on the step values provided.
      • heatmapEventTypePriority[] - Colors are assigned to cells if they include an event of the specified event type. Event types are prioritised by the index values of the array; the first index is given the highest priority.

      See the Heatmap Colors docs for details.

    • heatmapDirection
      copy link
      'any' | 'from' | 'to'default:'any'
      The direction of the joins at each entity row for the underlying events that the heatmap will show:
      • 'any' - Shows a heatmap for all underlying event directions.
      • 'from' - Only shows a heatmap for entity rows that are the source of their underlying events.
      • 'to' - Only shows a heatmap for entity rows that are the target of their underlying events.
    • heatmapPadding
      copy link
      booleandefault:true
      Whether to apply padding to heatmap cells.
    • heatmapThreshold
      copy link
      numberdefault:100
      The number of visible events when the heatmap starts fading in.
    • heatmapValue
      copy link
      string | nulldefault:null
      If a string, the value of the corresponding property on the event's data object is used for the heatmap. If null, the underlying event count is used.
    • joinStyle
      copy link
      'auto' | 'horizontal'default:'auto'
      Controls how events are drawn:
      • 'auto' - Automatically chooses the clearest way of drawing each event. Multi-directional events are drawn as a vertical line with horizontal arrowheads indicating the source/target role of each entity row, whereas uni-directional events are drawn as a single vertical arrow.
      • 'horizontal' - All events are drawn as a vertical line with horizontal arrowheads indicating the source/target role of each entity row.
    • revealHeatmapAlpha
      copy link
      numberdefault:1
      Alpha applied to fade out rows that have no revealed events.
    • showEventFolds
      copy link
      booleandefault:true
      Whether to show openable folds for events that occur at the same time. See the Event Folds docs for details.
    • showLines
      copy link
      'all' | 'focus'default:'all'
      Controls when to show event lines:
      • 'all' - Show event lines for all individual events.
      • 'focus' - Only show event lines for focused entities.
expandedRows
copy link
object
Beta
Options relating to expanding entity rows, see Expanded Rows.
    • durationEventsOnly
      copy link
      booleandefault:true
      Only entity rows with overlapping duration events are expanded.
    • showSubRowLines
      copy link
      booleandefault:false
      When entities are expanded, show lines for their sub-rows.
focus
copy link
object
Options relating to focus behavior.
    • backgroundColor
      copy link
      stringdefault:'#8b041b'
      The background color to use for focused items.
    • reorder
      copy link
      booleandefault:true
      Whether to reorder the entities on focus when the ordering is set to 'shorteneventlines'.
    • rescale
      copy link
      booleandefault:true
      Whether to rescale the events on focus when scaleMode is set to 'nonlinear'.
    • showEventsOnNeighbors
      copy link
      booleandefault:false
      Controls if all events on neighbors of focused entities should be shown. For example, if entity A is focused and is linked to entity B via an event, this option controls if all events involving entity B should be shown.
fontFamily
copy link
stringdefault:'sans-serif'
The name of the font family to use across the timeline.
highlightColor
copy link
stringdefault:'#515f6c'
The color to use for the background of highlighted entities, highlighted scale intervals and the marquee drag area. A translucent version of this color will be applied.
hover
copy link
numberdefault:150
The number of milliseconds delay before the hover event is triggered.
rangeEventDelay
copy link
numberdefault:500
The time, in milliseconds, between triggering range events. Note that adjusting this delay may interact with your application's flow rate and so cause unexpected changes in behavior.
scaleGuide
copy link
object
Options relating to the scale guide.
    • lineColor
      copy link
      stringdefault:'#e5e8eb'
      The color of the line.
    • showAtBottom
      copy link
      booleandefault:false
      Controls if the bottom time readout and scale guide line is shown.
    • showAtTop
      copy link
      booleandefault:false
      Controls if the top time readout and scale guide line is shown.
    • snapDistance
      copy link
      numberdefault:10
      The distance in pixels to snap the line to events. Set to 0 to disable snapping.
    • textColor
      copy link
      stringdefault:'#e5e8eb'
      The color of the text.
    • textFormat
      copy link
      stringdefault:'auto'
      The date and time format. Set to auto to have the scale precision adapt to the current visible range. See Localization for more details.
    • width
      copy link
      numberdefault:1
      The width of the line in pixels.
scales
copy link
object
Options relating to the timeline scales.
    • backgroundColor
      copy link
      string | nulldefault:null
      The color of the background of the scale. If null, backgroundColor is used.
    • borderColor
      copy link
      string | nulldefault:'#e5e8eb'
      The color of the scale borders. If null, backgroundColor is used.
    • dateOrder
      copy link
      'dmy' | 'mdy'default:'mdy'
      The order of dates:
      • 'dmy' - For day-month-year.
      • 'mdy' - For month-day-year.
    • dateTimeFormats
      copy link
      object
      Specifies the formats for displaying dates and times in the scale. See Localization for more details.
        • centiseconds
          copy link
          string
          1⁄100 of a second.
        • date
          copy link
          string
          Year, month, and day of month.
        • dateNoYear
          copy link
          string
          Month, and day of month.
        • dateNoYearTime
          copy link
          string
          Month, day of month, hour, and minutes.
        • dateNoYearTimeSeconds
          copy link
          string
          Month, day of month, hour, minutes, and seconds.
        • dateTimeSeconds
          copy link
          string
          Year, month, day of month, hour, minutes, and seconds.
        • dayOfMonth
          copy link
          string
          Day of month.
        • dayOfMonthTime
          copy link
          string
          Day of month, hour, and minutes.
        • dayOfMonthTimeSeconds
          copy link
          string
          Day of month, hour, minutes, and seconds.
        • fullDayOfWeek
          copy link
          string
          Full day of week.
        • fullDayOfWeekTime
          copy link
          string
          Full day of week, hour and minutes.
        • fullDayOfWeekTimeSeconds
          copy link
          string
          Full day of week, hour, minutes, and seconds.
        • fullMonth
          copy link
          string
          Full month.
        • fullMonthYear
          copy link
          string
          Year and full month.
        • hundredMicroseconds
          copy link
          string
          0.0001 of a second.
        • hundredNanoseconds
          copy link
          string
          0.0000001 of a second.
        • microseconds
          copy link
          string
          0.000001 of a second.
        • milliseconds
          copy link
          string
          1⁄1000 of a second.
        • nanoseconds
          copy link
          string
          0.000000001 of a second.
        • shortDayOfWeek
          copy link
          string
          Short day of week.
        • shortMonth
          copy link
          string
          Short month.
        • tenMicroseconds
          copy link
          string
          0.00001 of a second.
        • tenNanoseconds
          copy link
          string
          0.00000001 of a second.
        • time
          copy link
          string
          Hours and minutes.
        • timeSeconds
          copy link
          string
          Hour, minutes, and seconds.
        • timeSecondsTenths
          copy link
          string
          Hour, minutes, seconds, and 1⁄10 of seconds.
        • timeMilliseconds
          copy link
          string
          Hour, minutes, seconds, and 1⁄1000 of seconds.
        • timeMicroseconds
          copy link
          string
          Hour, minutes, seconds, and 1⁄1000000 of seconds.
        • timeNanoseconds
          copy link
          string
          Hour, minutes, seconds, and 1⁄1000000000 of seconds.
        • year
          copy link
          string
          Full year.
    • dateTimeNames
      copy link
      object
      Specifies names to use when displaying dates and times in the scale. See Localization for more details.
        • ampmNames
          copy link
          string[]
          The names of the AM and PM symbols.
        • fullDayOfWeekNames
          copy link
          string[]
          The full names of days of the week, starting with Sunday.
        • fullMonthNames
          copy link
          string[]
          The full names of months, starting with January.
        • fullMonthNamesInDate
          copy link
          string[]
          The full names of months as part of a date, starting with January.
        • shortDayOfWeekNames
          copy link
          string[]
          The short names of days of the week, starting with Sunday.
        • shortMonthNames
          copy link
          string[]
          The short names of months, starting with January.
    • fadeAtLeft
      copy link
      booleandefault:true
      Controls whether the scale fades at the left.
    • panLimit
      copy link
      'auto' | 'off'default:'auto'
      Controls how far the user can pan.
      • 'auto' - Limits the range the user can pan so data is always in view.
      • 'off' - Allows the user to pan to anywhere on the timeline. Use this option for lazy loading content.

      For 'nonlinear' scaleMode, the panLimit cannot be 'off'; it will always revert to the 'auto' behavior.

    • scaleMode
      copy link
      'linear' | 'nonlinear'default:'linear'
      Controls the spacing between events on the timeline.
    • showAtBottom
      copy link
      booleandefault:true
      Controls if the scale at the bottom of the timeline is shown.
    • showAtTop
      copy link
      booleandefault:true
      Controls if the scale at the top of the timeline is shown.
    • textColor
      copy link
      stringdefault:'#e5e8eb'
      The color of the scale's text. Also changes the color of the markers and their labels.
    • textSize
      copy link
      numberdefault:14
      The text size of the scale.
    • twelveHourClock
      copy link
      booleandefault:true
      Whether a 12-hour clock should be used. False specifies a 24-hour clock.
    • wrapping
      copy link
      'off' | 'day' | 'week' | 'month' | 'year'default:'off'
      Controls Scale Wrapping, i.e. the way time is wrapped in the scale:
      • 'off' - No wrapping, the scale shows time in a linear way.
      • 'day' - The scale shows the time since the start of the day.
      • 'week' - The scale shows the time since the start of the week.
      • 'month' - The scale shows the time since the start of the month.
      • 'year' - The scale shows the time since the start of the year.
    • zoomOutLimit
      copy link
      'auto' | objectdefault:'auto'
      Sets a limit for how far a user can zoom out.
      • 'auto' - The limit is set by KronoGraph

      Use the parameters to specify the limit. Can be used for lazy loading content to improve performance and loading times for large datasets. For 'nonlinear' scaleMode, the zoomOutLimit is always the 'auto' behavior; any specified limits will be ignored.

        • unit
          copy link
          'year' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second' | 'millisecond' | 'microsecond' | 'nanosecond'
          required
          Sets the time interval of the limit.
        • value
          copy link
          numberdefault:1
          Sets the multiple of the time interval.
selectionColor
copy link
stringdefault:'#f5f7fa'
Beta
The color to use to highlight selected events. A translucent version of this color will be applied.
showLensHighlight
copy link
booleandefault:true
Controls whether the lens highlight is shown, see Show Lens Highlight.
showWarnings
copy link
booleandefault:true
Controls if timeline warning messages are displayed in the console.
timeSeriesCharts
copy link
object
Options relating to time series charts.
    • position
      copy link
      'top' | 'bottom'default:'top'
      Position of time series charts in relation to the timeline.
    • sizePercent
      copy link
      numberdefault:25
      Percentage of the view height allocated to time series charts.

Data Formats

Items in KronoGraph such as entities, events or time series charts are described as plain JavaScript objects whose properties configure the appearance of each item. Events also describe their relationship to other entities. See the Timeline Items Docs for more details.

The formats below describe the data structures used to define items in the timeline.

Annotation

Beta
Defines an annotation drawn on specified events and entities.
  • borderColor
    copy link
    string | nulldefault:null
    The annotation body border color, or null for no border.
  • borderShape
    copy link
    'rectangle' | 'roundrect'default:'roundrect'
    The annotation body border shape.
  • borderStyle
    copy link
    'solid' | 'dashed'default:'solid'
    The annotation body border line style.
  • borderWidth
    copy link
    numberdefault:1
    The width of the border for the annotation body.
  • connectorStyle
    copy link
    object
    The style of the connector between the annotation and the annotated subject(s).
      • color
        copy link
        stringdefault:'#fff'
        The color of the connector line and container.
      • container
        copy link
        'none' | 'rectangle' | 'roundrect'default:'roundrect'
        The shape of the container to draw around the subject(s).
      • lineStyle
        copy link
        'solid' | 'dashed'default:'solid'
        The style of the connector line and container.
      • mergeContainers
        copy link
        booleandefault:false
        Whether to merge multiple containers together.
      • subjectEnd
        copy link
        'arrow' | 'dot' | 'circle' | 'none'default:'circle'
        The decoration shown at the subject end of the connector line.
      • width
        copy link
        numberdefault:1
        The width of the connector line and container.
  • fillColor
    copy link
    string | nulldefault:'#33353e'
    The annotation body fill color, or null for no fill.
  • fontSize
    copy link
    numberdefault:16
    The font size of the annotation body label.
  • label
    copy link
    string
    required
    The text for the annotation body.
  • labelColor
    copy link
    stringdefault:'#fff'
    The color of the text annotation body label.
  • position
    copy link
    object
    The position of the annotation relative to the subject(s) it annotates.
      • angle
        copy link
        string | numberdefault:'top'
        The angle at which the annotation is positioned relative to its subject(s). Use a compass point value ( 'n', 'ne' etc.) or integer degrees clockwise from the top. Use 'top' or 'bottom' to position the annotation in the top or bottom rail.
      • distance
        copy link
        numberdefault:10
        Distance between the annotation and its subject(s) in pixels.
  • subject
    copy link
    string | EntityRangeSubject | (string | EntityRangeSubject)[]
    required
    The subject or subjects to annotate: string ids for events or EntityRangeSubject objects for ranges of entity activity.

AnnotationBodyPosition

Beta
An object describing the annotation body position in view coordinates, which are measured in pixels relative to the top left corner of the timeline.
  • x1
    copy link
    number
    The x position at the left edge of the annotation body.
  • x2
    copy link
    number
    The x value at the right edge of the annotation body.
  • y1
    copy link
    number
    The y value at the top of the annotation body.
  • y2
    copy link
    number
    The y value at the bottom of the annotation body.

DraggerOptions

Options to set the drag.
  • type
    copy link
    'annotationScrollBar' | 'labelAreaWidth' | 'lensScrollbar' | 'marqueeRange' | 'marqueeSelection' | 'moveAnnotation' | 'pan' | null
    required
    The type of drag:
    • 'annotationScrollBar' - Scrolls the text of an annotation.
    • 'labelAreaWidth' - Changes the width of the entity label area.
    • 'lensScrollbar' - Scrolls through lens view.
    • 'marqueeRange' - Draws a marquee range. On drag-end, the default action is to zoom into the selected range.
    • 'marqueeSelection' - Draws a selection marquee.
    • 'moveAnnotation' - Moves the body of an annotation.
    • 'pan' - Pans the timeline.
    • null - No dragging behavior.

Entity

Defines an entity, an item drawn horizontally along the timeline.
  • color
    copy link
    string
    The color of the entity. If not specified, the value in the entity's type is used.
  • data
    copy link
    any
    Property for storing custom data for the entity.
  • fadeOutsideRange
    copy link
    boolean
    Controls if the entity line outside the range of events should be faded.
  • glyph
    copy link
    boolean | Glyph
    The glyph drawn for the entity's label. If false or not specified, no glyph is drawn.
  • label
    copy link
    string
    The text for the entity's label. If not specified, the entity's id is used.
  • labelColor
    copy link
    string
    The color of the entity labels. If not specified, the value in the entity's type is used.
  • lineWidth
    copy link
    number
    The width (thickness) of the entity's timeline in pixels. When using expanded rows, only applies to rows, not sub-rows. If not specified, the value in the entity's type is used.
  • type
    copy link
    stringdefault:'default'
    The type of the entity as declared in the entityTypes object. If not specified, the 'default' type is used. See the Entity Types docs.

EntityPosition

An object describing the entity position in view coordinates, which are measured in pixels relative to the top left corner of the timeline.
  • x1
    copy link
    number
    The x position at the left edge of the row containing the entity.
  • x2
    copy link
    number
    The x value at the right edge of the row containing the entity.
  • y1
    copy link
    number
    The y value at the top of the row containing the entity.
  • y2
    copy link
    number
    The y value at the bottom of the row containing the entity.

EntityRangeSubject

Beta
An object identifying a time range to annotate for a specified entity or entities.
  • id
    copy link
    string | string[]
    required
    Id of the entity or entities to annotate.
  • range
    copy link
    TimeRange
    required
    The time range to annotate for the entity or entities.
  • wrapping
    copy link
    ScaleWrappingdefault:'off'
    The scale wrapping that the annotation should appear for.

EntityType

Specifies the appearance and behavior of types of entities.
  • baseType
    copy link
    stringdefault:'default'
    The name of the entity type that this type inherits any unspecified properties from.
  • color
    copy link
    stringdefault:'#3ebd93'
    The color of entities of this type.
  • fadeOutsideRange
    copy link
    booleandefault:false
    Controls if entity lines outside their range of associated events are faded.
  • glyph
    copy link
    boolean | Glyph
    The glyph drawn for the label of entities of this type. If false or not specified, no glyph is drawn.
  • groupBy
    copy link
    string[]
    An array specifying the names of properties on the entity's data object used for grouping entities of this type, innermost first. For example: ['city', 'state', 'country'] will group by city, then state, then country.
  • labelColor
    copy link
    stringdefault:'#e5e8eb'
    The label color for entities of this type.
  • lineWidth
    copy link
    numberdefault:1
    The line width in pixels for entities of this type.
  • order
    copy link
    number
    A number specifying the display order for entities of this type. Entity types with lower values are placed higher. Entities with no specified order appear at the bottom.
  • typeGlyph
    copy link
    boolean | Glyph
    The glyph drawn in the label for a group of entities of this type. If false or not specified, no glyph is drawn.
  • typeLabel
    copy link
    string | false
    The text used to label a group of entities of this type. If false, no label is shown. If not specified, the type name is used.

Event

Defines an event, an item drawn on or between entities at a particular time.
  • color
    copy link
    string | 'from' | 'to' | 'entity' | 'inverse'
    The color of the event. Can be either a single color or one of the following values. Also applies to events with more than 2 entities.
    If not specified, the value in the event's type is used.
    • 'from' - Event takes its color from its first 'from' entity.
    • 'to' - Event takes its color from its first 'to' entity.
    • 'entity' - Event has a color gradient matching the color of each entity it joins with.
    • 'inverse' - Event has a color gradient with each end matching the opposite entity's color. For events with more than 2 entities, the color gradient follows the 'from' coloring behavior.
  • data
    copy link
    any
    Property for storing custom data for the event.
  • entityIds
    copy link
    string[] | { from: string | string[]; to?: string | string[] }
    required
    The ids of entities connected to the event. An event must have at least one connected entity. entityIds may be provided as:
    • An array of entity ids, where the event is directed from the first entity to the rest of the entities.
    • An object with from and to properties which determine the event direction in relation to each entity. These properties can be either a single string entity id, or an array of entity ids.
  • fontIcon
    copy link
    FontIcon
    Options to define the event's font icon.
  • label
    copy link
    Label
    Beta
    Options to define a label for the event line.
  • lineWidth
    copy link
    number | string
    The width of the event line.
    • If a number, is used directly as the line width in px units.
    • If a string, the value of the corresponding property on the event's data object is used instead, and an adjustment is applied to these values to even the distribution of the line widths throughout the dataset.
    • If not specified, the value in the event's type is used.
  • showArrows
    copy link
    boolean
    Controls if arrows on the event are shown. If not specified, the value in the event's type is used.
  • time
    copy link
    Date | number | TimeRange
    required
    Either a Date in local time, a millisecond number in UTC, or a TimeRange object.
  • timeNanoseconds
    copy link
    number
    The number of nanoseconds to add to the time value.
  • type
    copy link
    string
    The type of the event as declared in the eventTypes object. If not specified, the 'default' type is used. See the Event Types docs.

EventModifierKeys

A dictionary detailing which modifier keys were pressed when the event occurred.
  • alt
    copy link
    boolean
    If an alt key was held down when the event occurred.
  • consistentCtrl
    copy link
    boolean
    If a consistent control key was held down when the event occurred. cmd key on MacOS, ctrl key on other OSs.
  • ctrl
    copy link
    boolean
    If a control key was held down when the event occurred.
  • meta
    copy link
    boolean
    If the meta key was held down when the event occurred.
  • shift
    copy link
    boolean
    If a shift key was held down when the event occurred.

EventPosition

An object describing the event position in view coordinates, which are measured in pixels relative to the top left corner of the timeline.
  • x1
    copy link
    number
    The x position corresponding to the start time of the event.
  • x2
    copy link
    number
    The x position corresponding to the end time of the event.
  • y1
    copy link
    number
    The y value of the top of the event.
  • y2
    copy link
    number
    The y value of the bottom of the event.
  • wrappedSegments
    copy link
    { x1: number; x2: number }[]
    This property only applies when using Scale Wrapping. An array containing the x positions corresponding to the start and end times for each segment, ordered from left to right as they appear on the timeline. For most events, there is only one segment, so can be ignored.

EventType

Defines the appearance of types of events.
  • baseType
    copy link
    stringdefault:'default'
    The name of the event type that this type inherits any unspecified properties from.
  • color
    copy link
    string | 'from' | 'to' | 'entity' | 'inverse'default:'entity'
    The color of events of this type, either a single color or one of these values. Also applies to events with more than 2 entities.
    • 'from' - Event takes its color from its first 'from' entity.
    • 'to' - Event takes its color from its first 'to' entity.
    • 'entity' - Event has a color gradient matching the color of each entity it joins with.
    • 'inverse' - Event has a color gradient with each end matching the opposite entity's color. For events with more than 2 entities, the color gradient follows the 'from' coloring behavior.
  • fontIcon
    copy link
    FontIcon
    Options to define the font icon for events of this type.
  • label
    copy link
    Label
    Beta
    Options to define the event-line label for events of this type.
  • lineWidth
    copy link
    number | stringdefault:1.5
    The width of the event line for events of this type.
    • If a number, is used directly as the line width in px units.
    • If a string, the value of the corresponding property on the event's data object is used instead, and an adjustment is applied to these values to even the distribution of the line widths throughout the dataset.
  • showArrows
    copy link
    booleandefault:true
    Controls if arrows should be shown on events of this type.

ExpandedRows

Beta
An object specifying the entities whose rows are expanded (according to the expandedRows options), space permitting, and the expansion mode being used.
  • mode
    copy link
    'auto' | 'manual'
    The expansion mode being used:
    • 'auto' - Expand rows for all the entities.
    • 'manual' - Expand rows for just the entities specified in the list of ids.
  • ids
    copy link
    string | string[]
    If mode is 'manual', the ids of the entities whose rows are expanded (if space allows).

ExportResult

An object containing an image data URL.
  • url
    copy link
    string
    The URL containing the blob url for the exported image.

FontIcon

Defines the attributes of a font icon.
  • color
    copy link
    string
    The color of the font icon. Default is the timeline's background color.
  • dx
    copy link
    numberdefault:0
    The horizontal offset as a percentage of the font icon's size.
  • dy
    copy link
    numberdefault:0
    The vertical offset as a percentage of the font icon's size.
  • fontFamily
    copy link
    string
    The name of the icon font family.
  • fontWeight
    copy link
    number | stringdefault:'normal'
    The weight of the font.
  • scale
    copy link
    numberdefault:1
    The scale factor of the font icon.
  • text
    copy link
    string
    The text of the font icon. Can be an escaped character code or the icon character itself.

Glyph

Defines the attributes of a glyph.
  • color
    copy link
    string
    The color of the glyph.
  • fontIcon
    copy link
    FontIcon
    The font icon that is drawn on the glyph.

HeatmapColorStep

Defines a color to be used for heatmap cells with a value greater than or equal to the step value.
  • color
    copy link
    string
    required
    The color to be used for heatmap cells that are greater than or equal to the step value.
  • value
    copy link
    number
    required
    The step value.

HeatmapEventTypePriority

Defines a color to be used for a heatmap cell that includes an event of the specified type.
  • color
    copy link
    string
    required
    The color to be used for the heatmap cell.
  • eventType
    copy link
    string
    required
    The event type that one of the heatmap cells underlying events must include.

Label

Beta
Defines the attributes of a label.
  • backgroundColor
    copy link
    string | 'event'default:'event'
    The color of the label background.
  • color
    copy link
    stringdefault:'#242c32'
    The color of the label text.
  • hintColor
    copy link
    string | 'event'default:'event'
    The color of the label hint.
  • orientation
    copy link
    'up' | 'down' | 'horizontal'default:'horizontal'
    The orientation of the label.
  • shape
    copy link
    'roundrect' | 'rectangle'default:'roundrect'
    The shape of the label.
  • text
    copy link
    string | LabelFontIcon
    The text to display in the label.

LabelFontIcon

Beta
Defines the attributes of a font icon for an Event Label.
  • fontFamily
    copy link
    string
    The name of the icon font family.
  • fontWeight
    copy link
    number | stringdefault:900
    The weight of the font.
  • text
    copy link
    string
    required
    The text of the font icon. Can be an escaped character code or the icon character itself.

LabelAreaWidth

An object containing the mode of calculation for the width of the label area and the width.
  • mode
    copy link
    'auto' | 'fixed'
    The mode of calculation for the width of the label area:
    • 'auto' - The width is calculated automatically based on the visible entities.
    • 'fixed' - The width is fixed, but draggable.
  • width
    copy link
    number
    The width of the label area.

Marker

Defines a marker drawn across the timeline at a specified time.
  • color
    copy link
    string
    The color of the marker circle and line.
  • fontIcon
    copy link
    FontIcon
    Options to define the marker's font icon.
  • label
    copy link
    string
    required
    The text for the label of the marker.
  • labelColor
    copy link
    string
    The color of the marker label.
  • showAtBottom
    copy link
    boolean
    Whether to show the marker label and circle at the bottom of the timeline.
  • showAtTop
    copy link
    boolean
    Whether to show the marker label and circle at the top of the timeline.
  • showLine
    copy link
    boolean
    Whether to show the vertical marker line.
  • time
    copy link
    Date | number | TimeRange
    required
    The time that the marker is located at, either a Date in local time, a millisecond number in UTC, or a TimeRange object.
  • timeNanoseconds
    copy link
    number
    The number of nanoseconds to add to the time value.

SubItem

An object describing the targeted sub-item.
  • index
    copy link
    number
    The index of the sub-item.
  • subId
    copy link
    string
    Encoded information unique to the sub-item.
  • time
    copy link
    Date
    The time property of the sub-item.
  • timeNanoseconds
    copy link
    number
    The number of nanoseconds to add to the time value.
  • value
    copy link
    number
    The value property of the sub-item.
  • x
    copy link
    number
    The distance from the left edge of the Timeline element to the center of the sub-item.
  • y
    copy link
    number
    The distance from the top edge of the Timeline element to the center of the sub-item.
  • width
    copy link
    number
    The width of the sub-item in pixels.
  • height
    copy link
    number
    The height of the sub-item in pixels.

TimelineData

Defines the data to load into the timeline.
  • entities
    copy link
    object
    required
    A dictionary of entities to be displayed in the timeline, where the keys are the entity ids and the values are Entity objects. Ids must be unique across both entities and events.
  • entityTypes
    copy link
    object
    A dictionary of entity types, where the keys are the entity type names and the values are EntityType objects. May specify properties for the built-in 'default' entity type.
  • events
    copy link
    object
    required
    A dictionary of events to be displayed in the timeline, where the keys are the event ids and the values are Event objects. Ids must be unique across both entities and events.
  • eventTypes
    copy link
    object
    A dictionary of event types, where the keys are the event type names and the values are EventType objects. May specify properties for the built-in default event type.
  • ordering
    copy link
    'firstevent' | 'lastevent' | 'keyorder' | 'alphabetical' | 'shorteneventlines'default:'shorteneventlines'
    The ordering of entity groups, and entities within a group:
    • 'alphabetical' - Order alphabetically by the first letter of the entity labels.
    • 'firstevent' - Order by the time of the first event associated with the entity.
    • 'lastevent' - Order by the time of the last event of each entity (ascending).
    • 'keyorder' - Order by the indices of the entities data object.
    • 'shorteneventlines' - Order to shorten the vertical event lines between entities.
  • timeSeriesCharts
    copy link
    object
    A dictionary of time series charts, where the keys are the time series chart ids and the values are TimeSeriesChart objects. Ids must be unique.
  • timeSeriesChartStacks
    copy link
    object
    A dictionary of time series charts stacks, where the keys are the time series chart stack ids and the values are TimeSeriesChartStack objects. Ids must be unique.

TimeRange

A range of time.
  • end
    copy link
    Date | number
    required
    The end of the time range as a Date in local time, or a millisecond number in UTC.
  • endNanoseconds
    copy link
    number
    The number of nanoseconds to add to the end time value.
  • start
    copy link
    Date | number
    required
    The start of the time range as a Date in local time, or a millisecond number in UTC.
  • startNanoseconds
    copy link
    number
    The number of nanoseconds to add to the start time value.

TimeSeriesChart

Defines a time series chart.
  • color
    copy link
    string
    The color of the line connecting data points in the time series chart. An alpha value is applied to the area under the chart.
  • data
    copy link
    TimeSeriesChartDataPoint[]
    required
    The time series data.
  • fillAreaAlpha
    copy link
    numberdefault:0.3
    The alpha value applied to the area under the time series chart line. Set to 0 to remove the shaded area.
  • label
    copy link
    string
    The label for the time series chart. The label is not shown if the chart is in a stack.
  • labelColor
    copy link
    string
    The label color.
  • lineStyle
    copy link
    'solid' | 'dashed'default:'solid'
    The style of line connecting data points in the time series chart.
  • type
    copy link
    'linear' | 'step'default:'linear'
    The type of line connecting data points in the time series chart.

TimeSeriesChartDataPoint

A data point in a time series chart.
  • time
    copy link
    Date | number
    required
    Either a Date in local time or a millisecond number in UTC.
  • timeNanoseconds
    copy link
    number
    The number of nanoseconds to add to the time value.
  • value
    copy link
    number
    required
    The value of the data point.

TimeSeriesChartStack

Defines a time series chart stack.
  • chartIds
    copy link
    string[]
    required
    The ids of the time series charts included in the stack.
  • label
    copy link
    string
    The label for the stack.
  • labelColor
    copy link
    string
    The stack label's color.

Color Formats

Colors can be specified as a string in several formats:

  • One of the CSS named colors , e.g. 'red'
  • Shorthand hexadecimal colors, e.g. '#F00'
  • Hexadecimal colors, e.g. '#FF0000'
  • rgb or rgba formats, e.g. 'rgb(255, 0, 0)' or 'rgba(255, 0, 0, 0.5)'