Time Bar
The time bar shows items with date stamps in a histogram, showing volumes of activity over time.
Like the chart, it is populated by passing data into the items prop.
Time Bar Props
- animation object
Controls animations on the Time Bar.
- animate booleandefault:true
If true, animates changes.
- time numberdefault:250
The total duration in milliseconds in which animations should run.
- className string
If the Time Bar receives a
className, it will not apply any default styles. We recommend styling the Time Bar's parent element, rather than passing aclassNameto the Time Bar itself. - highlight array of objects
Highlights a time or range of times in the Time Bar using the color defined in the
highlightColoroption.<TimeBar highlight={[ new Date(), { start: Date.now() + 1000 * 60 * 60, end: Date.now() + 3 * 1000 * 60 * 60 } ]} />- end number | Date
The end of the range.
- start number | Date
The start of the range.
- items object
An indexed list of all the items in the Time Bar. Each item must have a
timesproperty. See the Item data format.- [id] Node | Link
An object describing a node or link.
- mode 'smooth' | 'histogram'default:'histogram'
Sets the display mode of the Time Bar to show histogram bars, or a smooth line with shaded area.
- options object
Specifies options on the Time Bar. See Time Bar Options.
- play booleandefault:false
Indicates whether the Time Bar is playing.
- range object
Specifies the visible range of the Time Bar.
- end number | Date
The end of the range.
- start number | Date
The start of the range.
- selection object | array of objects
Draws a selection line for items with truthy values in the supplied object, or multiple lines if multiple objects are supplied in an array. The maximum number of selection lines is 3.
<TimeBar items={items} selection={[{ node1: true }, { node2: true }]} />- [id] boolean
A truthy value indicates that an item should be included in the selection line.
- selectionColor string | array of stringsdefault:'sunset red', 'dark green' and 'orange'
Indicates the colors to use for any selection lines drawn.
<TimeBar items={items} selection={[{ node1: true }, { node2: true }]} selectionColor={["blue", "red"]} /> - style object
Standard styling properties for the element. We recommend styling the Time Bar's parent element, not the Time Bar itself. Default is:
{ position: 'relative', height: '100%', minHeight: '100px', width: '100%', }
Time Bar Events
In 3.0 we deprecated the onTimeBar- events.
- onChange onChangeHandler
Invoked whenever the range of the Time Bar changes. Returns a list of items in the updated range.
Parameters- change object
An object describing the change.
- items object
Shows which items are currently in the visible range.
- play boolean
Indicates if the play state has changed.
- range object
The current visible time-range, always returned as Date objects in the end user's time zone.
- end number | Date
The end of the range.
- start number | Date
The start of the range.
- onClick function
Invoked when the user clicks or taps on the time bar surface.
Parameters- props object
- button number
The index of the button used.
- end Date
The date at the end of the clicked range.
- index number
The index of the clicked selection point, or null for other click types.
- modifierKeys object
A dictionary detailing which modifier keys were pressed when the event occurred. See Modifier Keys.
- pointerId number
The unique identifier of the pointer.
- pointerType string
The type of pointing device.
- stackIndex number
Index of clicked stack in the bar. Undefined if
typeparameter is not 'bar' or the bar is highlighted. - stackValues array of numbers
Values of each stack in the bar. Undefined if
typeparameter is not 'bar' or the bar is highlighted. - start Date
The date at the start of the clicked range.
- tooltipX number
A suggested location for the tooltip in the x direction - the center of the bar or selection point.
- tooltipY number
A suggested location for the tooltip in the y direction - the height of the bar or selection point.
- type 'bar' | 'area' | 'selection' | 'scale' | 'left' | 'right' | 'slider' | null
The type of clicked item.
- value number
The value of either the bar or selection.
- x number
The x location of the pointer in view coordinates.
- y number
The y location of the pointer in view coordinates.
- onContextMenu function
Invoked on a right click, long press or left click + Ctrl for MacOS.
Default action: Suppresses the onClick event.
Parameters- props object
- button number
The index of the button used.
- defaultPrevented boolean
A read-only value indicating if the default action was prevented.
- end Date
The date at the end of the clicked range.
- index number
The index of the clicked selection point, or null for other click types.
- modifierKeys object
A dictionary detailing which modifier keys were pressed when the event occurred. See Modifier Keys.
- pointerId number
The unique identifier of the pointer.
- pointerType string
The type of pointing device.
- preventDefault function
Call to prevent the default action of the event.
- stackIndex number
Index of clicked stack in the bar. Undefined if
typeparameter is not 'bar' or the bar is highlighted. - stackValues array of numbers
Values of each stack in the bar. Undefined if
typeparameter is not 'bar' or the bar is highlighted. - start Date
The date at the start of the clicked range.
- tooltipX number
A suggested location for the tooltip in the x direction - the center of the bar or selection point.
- tooltipY number
A suggested location for the tooltip in the y direction - the height of the bar or selection point.
- type 'bar' | 'area' | 'selection' | 'scale' | 'left' | 'right' | 'slider' | null
The type of clicked item.
- value number
The value of either the bar or selection.
- x number
The x location of the pointer in view coordinates.
- y number
The y location of the pointer in view coordinates.
- onDoubleClick function
Invoked when the user double-clicks or double-taps on the time bar surface.
Default action: Animated zoom in that centres at the clicked time.
Parameters- props object
- button number
The index of the button used.
- defaultPrevented boolean
A read-only value indicating if the default action was prevented.
- end Date
The date at the end of the clicked range.
- index number
The index of the clicked selection point, or null for other click types.
- modifierKeys object
A dictionary detailing which modifier keys were pressed when the event occurred. See Modifier Keys.
- pointerId number
The unique identifier of the pointer.
- pointerType string
The type of pointing device.
- preventDefault function
Call to prevent the default action of the event.
- stackIndex number
Index of clicked stack in the bar. Undefined if
typeparameter is not 'bar' or the bar is highlighted. - stackValues array of numbers
Values of each stack in the bar. Undefined if
typeparameter is not 'bar' or the bar is highlighted. - start Date
The date at the start of the clicked range.
- tooltipX number
A suggested location for the tooltip in the x direction - the center of the bar or selection point.
- tooltipY number
A suggested location for the tooltip in the y direction - the height of the bar or selection point.
- type 'bar' | 'area' | 'selection' | 'scale' | 'left' | 'right' | 'slider' | null
The type of clicked item.
- value number
The value of either the bar or selection.
- x number
The x location of the pointer in view coordinates.
- y number
The y location of the pointer in view coordinates.
- onDragEnd function
Invoked when the drag is finished and pointer is released, or when the drag is canceled.
Default actions depending on drag
type:- 'slider' - Accepts the final panned range of the time bar and zooms to fit the view.
- other types - Accepts the final panned range of the time bar. Prevent the default action to snap the pan back.
Parameters- props object
- button number
The index of the button used.
- defaultPrevented boolean
A read-only value indicating if the default action was prevented.
- end Date
The date at the end of the clicked range.
- index number
The index of the clicked selection point, or null for other click types.
- modifierKeys object
A dictionary detailing which modifier keys were pressed when the event occurred. See Modifier Keys.
- pointerId number
The unique identifier of the pointer.
- pointerType string
The type of pointing device.
- preventDefault function
Call to prevent the default action of the event.
- stackIndex number
Index of clicked stack in the bar. Undefined if
typeparameter is not 'bar' or the bar is highlighted. - stackValues array of numbers
Values of each stack in the bar. Undefined if
typeparameter is not 'bar' or the bar is highlighted. - start Date
The date at the start of the clicked range.
- tooltipX number
A suggested location for the tooltip in the x direction - the center of the bar or selection point.
- tooltipY number
A suggested location for the tooltip in the y direction - the height of the bar or selection point.
- type 'bar' | 'area' | 'selection' | 'scale' | 'left' | 'right' | 'slider' | null
The type of clicked item.
- value number
The value of either the bar or selection.
- x number
The x location of the pointer in view coordinates.
- y number
The y location of the pointer in view coordinates.
- onDragStart function
Invoked when a drag is started.
Default actions depending on drag
type:- 'slider' - Starts dragging the slider.
- other types - Starts a pan controlled by the pointer. Prevent the default action to disable panning.
Parameters- props object
- button number
The index of the button used.
- defaultPrevented boolean
A read-only value indicating if the default action was prevented.
- end Date
The date at the end of the clicked range.
- index number
The index of the clicked selection point, or null for other click types.
- modifierKeys object
A dictionary detailing which modifier keys were pressed when the event occurred. See Modifier Keys.
- pointerId number
The unique identifier of the pointer.
- pointerType string
The type of pointing device.
- preventDefault function
Call to prevent the default action of the event.
- stackIndex number
Index of clicked stack in the bar. Undefined if
typeparameter is not 'bar' or the bar is highlighted. - stackValues array of numbers
Values of each stack in the bar. Undefined if
typeparameter is not 'bar' or the bar is highlighted. - start Date
The date at the start of the clicked range.
- tooltipX number
A suggested location for the tooltip in the x direction - the center of the bar or selection point.
- tooltipY number
A suggested location for the tooltip in the y direction - the height of the bar or selection point.
- type 'bar' | 'area' | 'selection' | 'scale' | 'left' | 'right' | 'slider' | null
The type of clicked item.
- value number
The value of either the bar or selection.
- x number
The x location of the pointer in view coordinates.
- y number
The y location of the pointer in view coordinates.
- onHover function
Invoked when the user hovers over an item. Only invoked whenever the hover id changes.
Parameters- props object
- button number
The index of the button used.
- end Date
The date at the end of the clicked range.
- index number
The index of the clicked selection point, or null for other click types.
- modifierKeys object
A dictionary detailing which modifier keys were pressed when the event occurred. See Modifier Keys.
- pointerId number
The unique identifier of the pointer.
- pointerType string
The type of pointing device.
- stackIndex number
Index of clicked stack in the bar. Undefined if
typeparameter is not 'bar' or the bar is highlighted. - stackValues array of numbers
Values of each stack in the bar. Undefined if
typeparameter is not 'bar' or the bar is highlighted. - start Date
The date at the start of the clicked range.
- tooltipX number
A suggested location for the tooltip in the x direction - the center of the bar or selection point.
- tooltipY number
A suggested location for the tooltip in the y direction - the height of the bar or selection point.
- type 'bar' | 'area' | 'selection' | 'scale' | 'left' | 'right' | 'slider' | null
The type of clicked item.
- value number
The value of either the bar or selection.
- x number
The x location of the pointer in view coordinates.
- y number
The y location of the pointer in view coordinates.
- onPointerDown function
Invoked when the pointer presses down on the time bar surface.
Parameters- props object
- button number
The index of the button used.
- end Date
The date at the end of the clicked range.
- index number
The index of the clicked selection point, or null for other click types.
- modifierKeys object
A dictionary detailing which modifier keys were pressed when the event occurred. See Modifier Keys.
- pointerId number
The unique identifier of the pointer.
- pointerType string
The type of pointing device.
- stackIndex number
Index of clicked stack in the bar. Undefined if
typeparameter is not 'bar' or the bar is highlighted. - stackValues array of numbers
Values of each stack in the bar. Undefined if
typeparameter is not 'bar' or the bar is highlighted. - start Date
The date at the start of the clicked range.
- tooltipX number
A suggested location for the tooltip in the x direction - the center of the bar or selection point.
- tooltipY number
A suggested location for the tooltip in the y direction - the height of the bar or selection point.
- type 'bar' | 'area' | 'selection' | 'scale' | 'left' | 'right' | 'slider' | null
The type of clicked item.
- value number
The value of either the bar or selection.
- x number
The x location of the pointer in view coordinates.
- y number
The y location of the pointer in view coordinates.
- onPointerMove function
Invoked continuously while the pointer moves on the time bar surface.
Parameters- props object
- button number
The index of the button used.
- end Date
The date at the end of the clicked range.
- index number
The index of the clicked selection point, or null for other click types.
- modifierKeys object
A dictionary detailing which modifier keys were pressed when the event occurred. See Modifier Keys.
- pointerId number
The unique identifier of the pointer.
- pointerType string
The type of pointing device.
- stackIndex number
Index of clicked stack in the bar. Undefined if
typeparameter is not 'bar' or the bar is highlighted. - stackValues array of numbers
Values of each stack in the bar. Undefined if
typeparameter is not 'bar' or the bar is highlighted. - start Date
The date at the start of the clicked range.
- tooltipX number
A suggested location for the tooltip in the x direction - the center of the bar or selection point.
- tooltipY number
A suggested location for the tooltip in the y direction - the height of the bar or selection point.
- type 'bar' | 'area' | 'selection' | 'scale' | 'left' | 'right' | 'slider' | null
The type of clicked item.
- value number
The value of either the bar or selection.
- x number
The x location of the pointer in view coordinates.
- y number
The y location of the pointer in view coordinates.
- onPointerUp function
Invoked when the pointer is released.
Parameters- props object
- button number
The index of the button used.
- end Date
The date at the end of the clicked range.
- index number
The index of the clicked selection point, or null for other click types.
- modifierKeys object
A dictionary detailing which modifier keys were pressed when the event occurred. See Modifier Keys.
- pointerId number
The unique identifier of the pointer.
- pointerType string
The type of pointing device.
- stackIndex number
Index of clicked stack in the bar. Undefined if
typeparameter is not 'bar' or the bar is highlighted. - stackValues array of numbers
Values of each stack in the bar. Undefined if
typeparameter is not 'bar' or the bar is highlighted. - start Date
The date at the start of the clicked range.
- tooltipX number
A suggested location for the tooltip in the x direction - the center of the bar or selection point.
- tooltipY number
A suggested location for the tooltip in the y direction - the height of the bar or selection point.
- type 'bar' | 'area' | 'selection' | 'scale' | 'left' | 'right' | 'slider' | null
The type of clicked item.
- value number
The value of either the bar or selection.
- x number
The x location of the pointer in view coordinates.
- y number
The y location of the pointer in view coordinates.
- onWheel function
Invoked continuously while the user is rotating a mouse wheel or scrolling using a trackpad.
Default action: Animated zoom in or out.
Parameters- props object
- defaultPrevented boolean
A read-only value indicating if the default action was prevented.
- deltaMode number
The unit of measurement for the delta value.
- deltaX number
The number of units that the wheel scrolled in the x direction.
- deltaY number
The number of units that the wheel scrolled in the y direction.
- modifierKeys object
A dictionary detailing which modifier keys were pressed when the event occurred. See Modifier Keys.
- preventDefault function
Call to prevent the default action of the event.
- x number
The x location of the pointer in view coordinates.
- y number
The y location of the pointer in view coordinates.
Time Bar Options
You can set various options and defaults on the time bar by setting the options prop.
<TimeBar
options={{
backgroundColor: 'rgb(60, 60, 60)',
style: {
color: 'blue',
hoverColor: 'red'
}
}}
/>The options prop accepts an object with the following format:
- backgroundColor stringdefault:'white'
The color to set the background of the Time Bar.
- changeEventThrottling numberdefault:250
The minimum interval between
onChangeevents in milliseconds. - heightChange object
Options controlling animation of height changes for histogram bars and selection lines.
- animate booleandefault:true
If true, animates changes.
- time numberdefault:250
The total duration in milliseconds in which animations should run.
- labels object
Options to control the appearance of labels on the Time Bar (used in the scales).
- color stringdefault:'gray'
The color to set the font of the Time Bar.
- fontFamily stringdefault:'sans-serif'
The default font family to use, such as 'arial' or 'helvetica'. If the font isn't supported by the browser, or if none is set, 'sans-serif' is used.
- fontSize numberdefault:12
The font size to use. There is no size limit, but most fonts look better if you use a value between 7 and 13.
- locale object
Specifies how dates and times are displayed.
- ampm array of stringsdefault:['AM', 'PM']
An array of two strings giving the text to use for AM and PM when displaying 12-hour clock times. Optionally this array may contain two more strings, which are used to label Time Bar intervals representing the first and second halves of days.
- h12 booleandefault:true
A flag indicating whether the 12-hour clock should be used to display times. If false, the 24-hour clock is used.
- half stringdefault:'H'
A prefix used to indicate halves of years.
- longMonths array of stringsdefault:['January', etc]
An array of strings giving the full names of the months, starting with January.
- order stringdefault:'mdy'
A string controlling the order of dates. Supported values are 'dmy' for day-month-year, and 'mdy' for month-day-year.
- quarter stringdefault:'Q'
A prefix used to indicate quarters of years.
- shortMonths array of stringsdefault:['Jan', 'Feb', ...etc]
An array of strings giving abbreviated names of the months, starting with January.
- playSpeed numberdefault:60
The speed that the Time Bar moves at when playing, in pixels per second. May be negative to animate backwards.
- scale object
Options for the minor and major time scales.
- hoverColor stringdefault:'light gray'
The color of the time scale section that is hovered over.
- showMajor booleandefault:true
Whether the major time scale (the lower scale) is shown.
- showMinor booleandefault:true
Whether the minor time scale (the higher scale) is shown.
- sliders object
Options to control the appearance of the sliders to the left and right of the histogram bars.
- color string
The color to set the sliders. The default is white with an opacity of 0.6.
- lineColor stringdefault:'gray'
The color to set the bars at the inner edge of the sliders.
- type 'none' | 'fixed' | 'free'default:'fixed'
Specifies slider behavior after a drag. Set to 'none' to hide the sliders.
- stack object
Specifies how to create stacked bars.
- by string
Splits histogram stacks by this value on an item's
dataproperty. Items which don't have a matching property will be grouped into an 'other' stack.const items = { a: { times: [Date.now()], data: { country: 'us' } }, b: { times: [Date.now()], data: { country: 'uk' } }, }; const stackOpts = { stack: { by: 'country' }}; return <TimeBar items={items} options={stackOpts} />
- styles Index
A dictionary of styles, where each property corresponds to a value for the
byproperty, and its value contains a definition of the styles to be applied to it.Stacks are stacked vertically upwards following the order of the styles defined in this object. The default time bar styling is used for the 'other' stack, containing items with no matching
byvalue.const items = { a: { times: [Date.now()], data: { country: 'us' } }, b: { times: [Date.now()], data: { country: 'uk' } }, }; const stackOpts = { stack: { by: 'country', styles: { us: { color: 'maroon', hoverColor: 'red' } }, uk: { color: 'navy', hoverColor: 'blue' } }, } } }; return <TimeBar items={items} options={stackOpts} />
- style object
Controls the appearance of histogram bars and smooth areas.
- color stringdefault:'light gray'
The color of the histogram bars or smooth area line.
- highlightColor stringdefault:'light red'
The color of histogram bars which contain highlighted times. Only available in histogram mode.
- highlightHoverColor stringdefault:'red'
The color of the highlighted histogram bars when they are hovered over. Only available in histogram mode.
- hoverColor stringdefault:'gray'
The color of the histogram bars when they are hovered over. Only available in histogram mode.
- zoom object
Specifies the bounds within which the user can zoom.
- max ZoomExtent
Sets the maximum zoom level (i.e., the smallest scale that the Time Bar will zoom in to). Note that this sets the smallest allowed scale, although the smallest scale actually realized may be larger.
- min ZoomExtent
Sets the minimum zoom level (i.e., the largest scale that the Time Bar will zoom out to). Note that this value should be larger than that set in the
maxobject, and if left unset, ReGraph calculates the range between the data's earliest and latest times and multiplies it by two.
Time Bar Instance Methods
- fit (items, options)
Fit the time bar to the items specified.
Parameters- items 'all' | array of strings | object
- options object
- time numberdefault:200
The time the animation should take, in milliseconds.
Returnsvoid - pan (direction, options)
Pan the time bar in the direction specified.
Parameters- direction 'forward' | 'backward'
- options object
- time numberdefault:200
The time the animation should take, in milliseconds.
Returnsvoid - zoom (direction, options)
Zoom the time bar in the manner specified.
Parameters- direction 'in' | 'out'
- options object
- time numberdefault:200
The time the animation should take, in milliseconds.
Returnsvoid