{% extends "base.html" %} {% block content %}

## 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 analytics 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.

{% endblock %} {% block scripts %}
{% endblock %}