The Timeline Component lets you represent a sequence of tracks and events over a time span.
<web-timeline></web-timeline>The Timeline Component is controllable through an imperative API.
<script>
const timeline = document.querySelector('web-timeline')
// set the start time to July 4th, 2023 (GMT)
timeline.startTime = '2023-07-04T00:00Z'
// set the current time to the middle of the same day
timeline.currentTime = '2023-07-04T12:00Z'
// set the end time to July 5th; the beginning of the next day.
timeline.endTime = '2023-07-05T00:00Z'
</script>The component is available from the npm registry:
npm install @astropub/timeline-componentThe <web-timeline> component can be added with classic JavaScript:
<script src="https://unpkg.com/@astropub/timeline-component/lib/classic"></script>The <web-timeline> component can also be added within JavaScript modules:
<script type="module">
import 'https://unpkg.com/@astropub/timeline-component/lib/module'
</script>The exact import path may differ, depending on the project and tooling:
<script type="module">
import '@astropub/timeline-component/lib/module'
</script>An Astro themed <web-timeline> component can be added with classic JavaScript or JavaScript modules:
<script src="https://unpkg.com/@astropub/timeline-component/lib/astro/classic"></script><script type="module">
import 'https://unpkg.com/@astropub/timeline-component/lib/astro/module'
</script>The <web-timeline> element itself can also be referenced from the JavaScript module:
<script type="module">
import { Timeline } from 'https://unpkg.com/@astropub/timeline-component/lib/astro/module'
</script>To add a track to the timeline, use the addTrack method:
const track = timeline.addTrack({
header: 'My Track'
})To add an event to a TimelineTrack, use the addEvent method:
const event = track.addEvent({
content: 'My Event',
startTime: '2022-07-04T05:00Z',
endTime: '2022-07-04T08:00Z',
})The Timeline component offers public methods that can be executed.
These methods are can be executed by setting a ViewChild decorator on the element.
import { Timeline } from '@astropub/timeline-component/lib/elements.js'
import { Component, ElementRef, ViewChild, Input, OnChanges } from '@angular/core'
if (!customElements.get('web-timeline')) {
customElements.define('web-timeline', Timeline)
}
@Component({
selector: 'app-timeline',
template: `<web-timeline #timeline></web-timeline>`,
})
export class TimelineComponent implements OnChanges {
@ViewChild('timeline') timelineComponent: ElementRef
}The Timeline interface represents the timeline and all of its tracks and events.
import { Timeline } from '@astropub/timeline-component/lib/astro/module'
const timeline = new Timeline({
startTime: '2023-07-04T00:00Z',
currentTime: '2023-07-04T08:00Z',
endTime: '2023-07-05T00:00Z'
})The startTime property represents the starting point of the timeline.
This value can be provided as a number, as an epoch time, or as a Date object.
// set the start time to July 4th, 2023 (GMT)
timeline.startTime = 1688428800000
timeline.startTime = '2023-07-04T00:00Z'
timeline.startTime = new Date('2023-07-04T00:00Z')The currentTime property represents the current point in the timeline.
This value can be provided as a number, as an epoch time, or as a Date object.
// set the start time to noon of July 4th, 2023 (GMT)
timeline.currentTime = 1688472000000
timeline.currentTime = '2023-07-04T12:00Z'
timeline.currentTime = new Date('2023-07-04T12:00Z')The endTime property represents the ending point of the timeline.
This value can be provided as a number, as an epoch time, or as a Date object.
// set the end time to July 5th, 2023 (GMT)
timeline.endTime = 1688515200000
timeline.endTime = '2023-07-05T00:00Z'
timeline.endTime = new Date('2023-07-05T00:00Z')The zoom property represents the length at which time appears in the timeline.
This value can be provided as a number.
// zoom out to 1/100th the current size
timeline.zoom = 0.01
// zoom in to 100x the current size
timeline.zoom = 1000The tracks property represents the list of tracks within the timeline.
The tracks property returns the DOM children representing all of the tracks.
When set as an Array, its value replaces all of the current tracks.
const firstTrack = timeline.tracks[0]The addTrack method adds a new track to the given timeline.
timeline.addTrack({
header: 'My Track',
open: true,
})The addTrack method accepts the following options:
- The
headerproperty defines the header content for the given track. - The
openproperty determines whether the track should display expanded or collapsed.
The TimelineTrack interface represents a grouping for related events along a timeline.
Tracks contain events, and they can also container other tracks; subtracks.
track.header = 'My Track'
track.addEvent({
content: 'My Event",
startTime: '2022-07-04T05:00Z',
endTime: '2022-07-04T08:00Z',
})The header property represents the header content for the given track.
It returns the DOM Element container for the track header.
When set, its value is appended to the track header.
track.header = 'My Track'
track.header.classList.add('my-track')The tracks property represents the list of subtracks within a given track.
The tracks property returns the DOM children representing all of the subtracks.
When set as an Array, its value replaces all of the current tracks.
const firstSubTrack = track.tracks[0]The open property represents whether the track is expanded or collapsed.
The open property returns true or false.
When set as an Boolean, it will expand or collapse the track if it contains subtracks.
The addEvent method adds a new event to the given track.
track.addEvent({
content: 'My Event',
startTime: '2022-07-04T05:00Z',
endTime: '2022-07-04T08:00Z',
status: 'standby',
})The addEvent method accepts the following options:
- The
contentproperty defines the content for the given event. - The
startTimeproperty determines the starting point of the given event. - The
endTimeproperty determines the ending point of the given event.
The addTrack method adds a new subtrack to the given track.
track.addTrack({
header: 'My Sub-Track',
open: true,
})The addTrack method accepts the following options:
- The
headerproperty defines the header content for the given track. - The
openproperty determines whether the track should display expanded or collapsed.
The TimelineEvent interface represents an event within a given track.
The startTime property represents the starting point of a given event.
This value can be provided as a number, as an epoch time, or as a Date object.
// set the start time to 8 hours into July 4th, 2023 (GMT)
event.startTime = 1688457600000
event.startTime = '2023-07-04T08:00Z'
event.startTime = new Date('2023-07-04T08:00Z')The endTime property represents the ending point of a given event.
This value can be provided as a number, as an epoch time, or as a Date object.
// set the end time to 12 hours into July 4th, 2023 (GMT)
event.endTime = 1688472000000
event.endTime = '2023-07-04T12:00Z'
event.endTime = new Date('2023-07-04T12:00Z')The content property represents the content of the event.
It returns the DOM Element container.
When set, its value is appended to the event.
event.content = 'My Event'
event.content.classList.add('my-event')The track part can be used to style the outermost area of tracks.
web-timeline::part(track) {
background-color: Indigo;
}The track-header part can be used to style the header area of tracks.
web-timeline::part(track-header) {
background-color: Indigo;
}The event part can be used to style the outermost area of events.
web-timeline::part(event) {
background-color: Indigo;
}The content property of an event can be used to target or replace the content of a given event.
const template = document.createElement('template')
template.innerHTML = 'This is <strong>my event</strong>'
event.content = template.content