TimelineJS options

When you create a timeline manually by calling TL.Timeline, you may pass in an optional third parameter which contains a variety of presentation options. This third parameter should be a Javascript object with keys matching the value in the Name column and corresponding values appropriate to the specific key. For example:

  var options = {
    hash_bookmark: false,
    initial_zoom: 5
  }
  var timeline = new TL.Timeline('timeline-embed',
                                 'https://docs.google.com/spreadsheets/d/1cWqQBZCkX9GpzFtxCWHoqFXCHg-ylTVUWlnrdYMzKUI/pubhtml',
                                 options);
      

If you use our authoring tool, you can pass most of these as URL parameters. Add &option_name=value for each. To demonstrate using the same options as above: https://cdn.knightlab.com/libs/timeline3/latest/embed/index.html?source=1cWqQBZCkX9GpzFtxCWHoqFXCHg-ylTVUWlnrdYMzKUI&font=Default&lang=en&initial_zoom=3&height=650&hash_bookmark=false

Name
Default value
Notes
font
default

May be one of a list of Timeline's "built-in" font sets, or a full or relative URL (ending in .css) which points to a CSS file in the same format as the built-ins. (See the typography section of "Overriding Timeline's Styles")

The valid values for the built-in fonts are:

  • abril-droidsans
  • amatic-andika
  • bevan-pontanosans
  • bitter-raleway
  • clicker-garamond
  • dancing-ledger
  • default
  • fjalla-average
  • georgia-helvetica
  • lustria-lato
  • medula-lato
  • oldstandard
  • opensans-gentiumbook
  • playfair-faunaone
  • playfair
  • pt
  • roboto-megrim
  • rufina-sintony
  • ubuntu
  • unicaone-vollkorn

debug
false
If true, copious console logging will be enabled.
height
this._el.container.offsetHeight
The height of the timeline.
width
this._el.container.offsetWidth
The width of the timeline.
is_embed
false
If true, the class tl-timeline-embed is added to the outer Timeline container. Typically only used to support Timeline iframe embeds.
hash_bookmark
false
If set to true, TimelineJS will update the browser URL each time a slide advances, so that people can link directly to specific slides.
default_bg_color
white
RGB values to use for slide backgrounds. Specify as hex code, CSS named color, or a Javascript object with r, g, and b properties from 0-255.
scale_factor
2
How many screen widths wide the timeline should be at first presentation.
initial_zoom
The position in the zoom_sequence series used to scale the Timeline when it is first created. Takes precedence over scale_factor.
zoom_sequence
[0.5, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
Array of values for TimeNav zoom levels. Each value is a scale_factor, which means that at any given level, the full timeline would require that many screens to display all events.
timenav_position
"bottom"
Display the timeline nav on the top or bottom.
optimal_tick_width
100
Optimal distance (in pixels) between ticks on axis.
base_class
"tl-timeline"
Removing the tl-timeline base class will disable all default stylesheets.
timenav_height
150
The height in pixels of the timeline nav. Takes precedence over timenav_height_percentage.
timenav_height_percentage
25
Specify the timeline nav height as a percentage of the screen instead of in pixels.
timenav_mobile_height_percentage
40
Specify the timeline nav height as a percentage of a mobile device screen.
timenav_height_min
150
The minimum timeline nav height (in pixels).
marker_height_min
30
The minimum marker height (in pixels).
marker_width_min
100
The minimum marker witdh (in pixels).
marker_padding
5
Top and bottom padding (in pixels) for markers.
start_at_slide
0
The first slide to display when the timeline is loaded.
start_at_end
false
If true, loads timeline on last slide.
menubar_height
0
use_bc
false
Use declared suffix on dates earlier than 0.
duration
1000
Animation duration (in milliseconds).
ease
TL.Ease.easeInOutQuint
dragging
true
trackResize
true
slide_padding_lr
100
Padding (in pixels) on the left and right of each slide.
slide_default_fade
"0%"
language
"en"

Value should be a language code for a translation set included with TimelineJS. See the Github repository for the set of supported language codes—to use these, specify the filename without the .json extension.

Alternatively, you can create your own translation file, for other languages or simply to override the default messages. To do this, specify a URL to a file based on en.json. Your URL must end in .json.

ga_property_id
null
Google Analytics ID.
track_events
['back_to_start', 'nav_next', 'nav_previous', 'zoom_in', 'zoom_out']
script_path
""
Can be used to help Timeline load related resources such as CSS themes and language files. Rarely needs to be set, except if you are bundling the TimelineJS javascript code with other javascript, so that the script it load from isn't in the same "relative" location to your local copy of those resources.