Timeline
avonni-dd-timeline
The Avonni Data Driven Timeline displays records in a timeline view.
Overview
Timeline is a data-driven Lightning Web Component that displays records in a chronological timeline view, placing each item on a time axis by its date.
The Timeline works in two modes. In query mode, you provide a query and a mapping, and the component fetches records and maps their fields to timeline items automatically—complete with filters, search, pagination, and header actions. In static mode, you pass a fixed array of items directly; the component then ignores query and mapping and renders exactly what you give it.
Use Cases
Activity history: Show Tasks, Events, or other activities for a record in chronological order.
Project milestones: Display a fixed set of milestones with status and custom icons.
Account or contact timelines: Surface related records ordered by their created or activity date.
Release roadmaps: Render planned releases grouped by month or year.
Audit trails: Present a paginated, searchable history of changes.
Case lifecycles: Track the progression of a case across key dated events.
Use Case Examples
Example 1: Query mode
Scenario: Display a record's Tasks in a vertical timeline grouped by month, with search, filters, pagination, and per-item actions.
Result: A vertical, collapsible timeline of Task records grouped by month. Each item shows the Subject, Description, Status, and Priority, with search, filters, pagination, and a "See more"/"Delete" action menu. Clicking an item or action fires the corresponding event with both the mapped item and the raw record.
Example 2: Static mode
Scenario: Render a fixed release roadmap from a hardcoded array of milestones—no query needed.
Result: A vertical timeline of three milestones grouped by month with custom icons. The Beta release item shows a selection checkbox, and the GA release item is marked active. Because no query runs, itemSObject is null in the events.
Specifications
Attributes
actions
Array of actions. They are displayed at the top right of each item.
DdTimelineAction[]
—
allow-item-click
If true, the timeline items are displayed as clickable, and a click on an item fires the itemclick event.
Boolean
false
fields
Array of field API names that belong to the queried object. The fields will be displayed in the timeline items, with their corresponding values.
string[]
—
fields-attributes
Object defining the fields layout.
DdTimelineFieldsAttributes
—
filters
Array of field API names that belong to the queried object. These fields will be displayed as user filters.
string[]
—
filters-attributes
Object defining the filters-specific attributes.
DdElementFiltersAttributes
—
header-actions
Array of actions to display at the top right of the header. On click on a header action, the headeractionclick event is fired.
DdElementAction[]
—
header-avatar
Avatar displayed at the top left of the header.
DdElementAvatar
—
header-caption
Header caption, displayed above the title.
String
—
header-help-text
If present, a help text icon is displayed next to the header title. On focus or hover on the icon, the header help text is displayed in a tooltip.
String
—
header-help-text-attributes
Object defining the help text-specific attributes.
DdElementHelpTextAttributes
—
header-title
Main title displayed in the header.
String
—
header-visible-actions-count
Number of header actions that appear as regular buttons. Remaining actions appear in a dropdown menu.
integer
—
hide-no-results-image
If true, the image displayed when the query returns no results is hidden.
Boolean
false
hide-no-results-message
If true, the message displayed when the query returns no results is hidden.
Boolean
false
item-date-format
Object defining the item date format.
DdTimelineItemDateFormat
—
item-icon-size
The size of the icon. Valid values are xx-small, x-small, small, medium and large.
String
"small"
items
Array of static items displayed in the timeline. When this property is set, the timeline ignores the query and mapping properties and displays the items directly.
DdTimelineItem[]
—
items-per-page
If the pagination is enabled, number of items per page. Otherwise, number of items loaded at once.
integer
100
mapping
Object defining the way the records returned by the query should be mapped to the timeline item properties. To insert the value of a field, use the syntax {{Record.FieldApiName}}. For example, to use the value of the Name field, use {{Record.Name}}.
DdTimelineMapping
—
no-results-message
Message displayed when the query returns no results.
String
—
orientation
Orientation of the activity timeline. Valid values are vertical and horizontal.
String
"horizontal"
orientation-attributes
Object defining the orientation-specific attributes.
DdTimelineOrientationAttributes
—
pagination-attributes
Object defining the pagination-specific attributes.
DdElementPaginationAttributes
—
query
Definition of the query to execute to get the records that will be mapped.
DdElementQuery
—
refresh-emp
Object describing a platform event that should be subscribed to in order to refresh the component when an event is published.
DdElementRefreshEmp
—
search-attributes
Object defining the search-specific attributes.
DdElementSearchAttributes
—
search-fields
Array of field API names that can be used by the search box to filter the records. The fields must belong to the queried object, and they must be filterable.
string[]
—
selected-items-names
Array of selected item names. These represent the unique names of items that are currently selected in the timeline. Updated automatically when items are selected or unselected.
string[]
—
show-pagination
If true, a pagination is displayed at the bottom of the timeline. If false and the timeline has a height limit, the items will be loaded dynamically as the user scrolls. If false and the timeline does not have a height limit, a "show more" button will be displayed at the bottom of the timeline.
Boolean
false
side-panel-attributes
Object defining the side panel-specific attributes.
DdElementSidePanelAttributes
—
total-nb-items
Total number of records available in static mode. Set this property when you load the items yourself and want to load them progressively: the component then fires the loadmore event (when the pagination is disabled) or the pagechange event (when the pagination is enabled) so you can load the next records and update the items array. When left undefined, the provided items array is paginated on the client and these events are not fired. This property has no effect in query mode.
integer
—
Mapping
In query mode, mapping tells the Timeline how to turn each queried record into an item. Insert a field value with the {{Record.FieldApiName}} syntax.
label
Item title.
name
Unique item identifier (usually {{Record.Id}}). Required.
description
Item description text.
startDate
Date used to position the item on the timeline.
endDate
Optional end date of the item.
avatar
Avatar object (src, initials, fallbackIconName, presence).
hasCheckbox
If true, shows a selection checkbox before the item label.
href
URL the item links to.
linkify
If true, links the label to the record page (overrides href).
isActive
If true, marks the item as active.
Methods
refresh
Refresh the query and the records displayed in the component.
stayOnCurrentPage
Boolean
If true, the component will refresh but stay on the current page.
Custom Events
actionclick
Event fired when an item action is clicked.
The actionclick event returns the following parameters.
name
string
Name of the action clicked.
item
object
Timeline item the action belongs to, with the mapped label, name, description, startDate and endDate properties.
record
object
Record corresponding to the item the action belongs to. In static mode, no record is associated and this is null.
The event properties are as follows.
bubbles
false
This event does not bubble.
cancelable
false
This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed
false
This event does not propagate outside of the component in which it was dispatched.
error
The event fired when an error occurs in the component.
The error event returns the following parameters.
message
string
Message of the error.
The event properties are as follows.
bubbles
false
This event does not bubble.
cancelable
false
This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed
false
This event does not propagate outside of the component in which it was dispatched.
filter
The event fired when the user filters the records.
The filter event returns the following parameters.
value
object
Object containing the filters applied by the user. Its keys correspond to the field API names of the selected filters. The values are arrays of strings, corresponding to the values selected for the filter.
The event properties are as follows.
bubbles
false
This event does not bubble.
cancelable
false
This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed
false
This event does not propagate outside of the component in which it was dispatched.
headeractionclick
The event fired when a header action is clicked.
The headeractionclick event returns the following parameters.
name
string
Name of the action clicked.
The event properties are as follows.
bubbles
false
This event does not bubble.
cancelable
false
This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed
false
This event does not propagate outside of the component in which it was dispatched.
itemclick
Event fired when an item is clicked.
The itemclick event returns the following parameters.
item
object
Timeline item that was clicked, with the mapped label, name, description, startDate and endDate properties.
record
object
Record corresponding to the item that was clicked. In static mode, no record is associated and this is null.
The event properties are as follows.
bubbles
false
This event does not bubble.
cancelable
false
This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed
false
This event does not propagate outside of the component in which it was dispatched.
loadmore
The event fired in static mode, when the user reaches the end of the component and more records remain to load (infinite loading). It is only fired when totalNbItems is set and the pagination is disabled. Load the next records and append them to the items array.
The loadmore event returns the following parameters.
search
string
Current search value, when the search box is used. Apply it when loading the next records.
setIsLoading
function
Callback toggling the component loading state while the next records are loaded. Call setIsLoading(true) before loading the records and setIsLoading(false) once they are loaded.
The event properties are as follows.
bubbles
false
This event does not bubble.
cancelable
false
This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed
false
This event does not propagate outside of the component in which it was dispatched.
nbitemschange
The event fired when the number of items displayed in the component changes.
The nbitemschange event returns the following parameters.
value
integer
Number of items displayed in the component.
The event properties are as follows.
bubbles
false
This event does not bubble.
cancelable
false
This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed
false
This event does not propagate outside of the component in which it was dispatched.
pagechange
The event fired in static mode, when the user navigates to another page or changes the search value. It is only fired when totalNbItems is set and the pagination is enabled. Load the records of the new page (applying the search) and replace the items array.
The pagechange event returns the following parameters.
value
integer
New page number.
search
string
Current search value, when the search box is used. Apply it when loading the page records.
setIsLoading
function
Callback toggling the component loading state while the new page records are loaded. Call setIsLoading(true) before loading the records and setIsLoading(false) once they are loaded.
The event properties are as follows.
bubbles
false
This event does not bubble.
cancelable
false
This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed
false
This event does not propagate outside of the component in which it was dispatched.
select
Event fired when the item selection is updated. If items are checked by default, this event will be fired when the query is first executed. It is also fired when items are checked or unchecked by the user.
The select event returns the following parameters.
item
object
Timeline item that was checked or unchecked, with the mapped label, name, description, startDate and endDate properties.
record
object
Record corresponding to the item that was checked or unchecked. In static mode, no record is associated and this is null.
selected
boolean
True if the item was checked, false if it was unchecked.
selectedItemsNames
string[]
Array of item key names, corresponding to the current selection.
The event properties are as follows.
bubbles
false
This event does not bubble.
cancelable
false
This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed
false
This event does not propagate outside of the component in which it was dispatched.
actionclick
Event fired when an item action is clicked.
The actionclick event returns the following parameters.
name
string
Name of the action clicked.
item
object
Timeline item the action belongs to, with the mapped label, name, description, startDate and endDate properties.
itemSObject
object
Record corresponding to the item the action belongs to. In static mode, no record is associated and this is null.
The event properties are as follows.
bubbles
false
This event does not bubble.
cancelable
false
This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed
false
This event does not propagate outside of the component in which it was dispatched.
error
The event fired when an error occurs in the component.
The error event returns the following parameters.
message
string
Message of the error.
The event properties are as follows.
bubbles
false
This event does not bubble.
cancelable
false
This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed
false
This event does not propagate outside of the component in which it was dispatched.
filter
The event fired when the user filters the records.
The filter event returns the following parameters.
value
object
Object containing the filters applied by the user. Its keys correspond to the field API names of the selected filters. The values are arrays of strings, corresponding to the values selected for the filter.
The event properties are as follows.
bubbles
false
This event does not bubble.
cancelable
false
This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed
false
This event does not propagate outside of the component in which it was dispatched.
headeractionclick
The event fired when a header action is clicked.
The headeractionclick event returns the following parameters.
name
string
Name of the action clicked.
The event properties are as follows.
bubbles
false
This event does not bubble.
cancelable
false
This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed
false
This event does not propagate outside of the component in which it was dispatched.
itemclick
Event fired when an item is clicked.
The itemclick event returns the following parameters.
item
object
Timeline item that was clicked, with the mapped label, name, description, startDate and endDate properties.
itemSObject
object
Record corresponding to the item that was clicked. In static mode, no record is associated and this is null.
The event properties are as follows.
bubbles
false
This event does not bubble.
cancelable
false
This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed
false
This event does not propagate outside of the component in which it was dispatched.
nbitemschange
The event fired when the number of items displayed in the component changes.
The nbitemschange event returns the following parameters.
value
integer
Number of items displayed in the component.
The event properties are as follows.
bubbles
false
This event does not bubble.
cancelable
false
This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed
false
This event does not propagate outside of the component in which it was dispatched.
pagechange
The event fired when the page changes.
The pagechange event returns the following parameters.
value
integer
New page number.
The event properties are as follows.
bubbles
false
This event does not bubble.
cancelable
false
This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed
false
This event does not propagate outside of the component in which it was dispatched.
select
Event fired when the item selection is updated. If items are checked by default, this event will be fired when the query is first executed. It is also fired when items are checked or unchecked by the user.
The select event returns the following parameters.
item
object
Timeline item that was checked or unchecked, with the mapped label, name, description, startDate and endDate properties.
itemSObject
object
Record corresponding to the item that was checked or unchecked. In static mode, no record is associated and this is null.
selected
boolean
True if the item was checked, false if it was unchecked.
selectedItemsNames
string[]
Array of item key names, corresponding to the current selection.
The event properties are as follows.
bubbles
false
This event does not bubble.
cancelable
false
This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed
false
This event does not propagate outside of the component in which it was dispatched.
Styling Hooks
--avonni-dd-timeline-footer-color-background
color
—
--avonni-dd-timeline-footer-color-border
color
—
--avonni-dd-timeline-footer-radius-border
string
—
--avonni-dd-timeline-footer-sizing-border
string
—
--avonni-dd-timeline-footer-styling-border
string
—
--avonni-dd-timeline-header-actions-color-background
color
—
--avonni-dd-timeline-header-actions-color-background-active
color
—
--avonni-dd-timeline-header-actions-color-background-hover
color
—
--avonni-dd-timeline-header-actions-color-border
color
—
--avonni-dd-timeline-header-actions-color-border-active
color
—
--avonni-dd-timeline-header-actions-color-border-hover
color
—
--avonni-dd-timeline-header-actions-text-color
color
—
--avonni-dd-timeline-header-actions-text-color-active
color
—
--avonni-dd-timeline-header-actions-text-color-hover
color
—
--avonni-dd-timeline-header-caption-font-family
string
—
--avonni-dd-timeline-header-caption-font-size
dimension
—
--avonni-dd-timeline-header-caption-font-style
string
normal
--avonni-dd-timeline-header-caption-font-weight
number
400
--avonni-dd-timeline-header-caption-letter-spacing
string
—
--avonni-dd-timeline-header-caption-line-height
string
—
--avonni-dd-timeline-header-caption-text-color
color
#000000
--avonni-dd-timeline-header-color-background
color
—
--avonni-dd-timeline-header-color-border
color
—
--avonni-dd-timeline-header-color-border-bottom
color
#c9c9c9
--avonni-dd-timeline-header-icon-color-background
color
—
--avonni-dd-timeline-header-icon-color-foreground
color
—
--avonni-dd-timeline-header-icon-color-foreground-default
color
—
--avonni-dd-timeline-header-icon-radius-border
string
—
--avonni-dd-timeline-header-margin-block-end
dimension
—
--avonni-dd-timeline-header-radius-border
string
—
--avonni-dd-timeline-header-sizing-border
string
—
--avonni-dd-timeline-header-sizing-border-bottom
dimension
1px
--avonni-dd-timeline-header-spacing-block-end
dimension
0.75rem
--avonni-dd-timeline-header-spacing-block-start
dimension
0.75rem
--avonni-dd-timeline-header-spacing-inline-end
dimension
1rem
--avonni-dd-timeline-header-spacing-inline-start
dimension
1rem
--avonni-dd-timeline-header-styling-border
string
—
--avonni-dd-timeline-header-styling-border-bottom
string
solid
--avonni-dd-timeline-header-title-font-family
string
—
--avonni-dd-timeline-header-title-font-size
dimension
1rem
--avonni-dd-timeline-header-title-font-style
string
normal
--avonni-dd-timeline-header-title-font-weight
number
400
--avonni-dd-timeline-header-title-letter-spacing
string
—
--avonni-dd-timeline-header-title-line-height
number
1.25
--avonni-dd-timeline-header-title-text-color
color
#080707
--avonni-dd-timeline-icon-color-background
color
—
--avonni-dd-timeline-icon-color-foreground
color
—
--avonni-dd-timeline-icon-color-foreground-default
color
—
--avonni-dd-timeline-icon-radius-border
string
—
--avonni-dd-timeline-item-color-background
color
#c9c7c5