《 Back to main documentation page

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_measurement_id
null
Google Measurement ID. For self-hosted timelines, if this value is set, then Google Analytics 4 will be initialized and pageviews and other navigation events will be logged to the given measurement ID. For Knight Lab hosted timelines, this cannot be overridden with your measurement ID.
ga_property_id
null
Google Analytics ID. This option is deprecated in favor of ga_measurement_id which better matches Google Analytics 4 (GA4) language. For now, if ga_property_id is set and ga_measurement_id is not, then ga_property_id will be used, even though the code is designed for GA4.
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.
soundcite
false

If this option is set to true, then TimelineJS will load the code necessary to support clips created using Knight Lab's SoundciteJS. This eliminates the need to add the embed code shown in step 3 of the Soundcite authoring tool. Simply copy the per-clip markup from step 2 into the "text" field for any TimelineJS event.

Note that while the default value for this option is false, for timelines hosted on Knight Lab's systems, the value is set to true for ease of use.