Properties

Core Props

activeItemIndex

Type: number
Default: 0

This property sets the default active timeline item that should be displayed when the component loads.

allowDynamicUpdate

Type: boolean
Default: false

This property allows timeline items to be updated dynamically. If true, changes to the items prop will re-render the timeline.

items

Type: TimelineItemModel[]
Default: []

An array of Timeline Item objects to display. Each item can contain properties like title, cardTitle, cardSubtitle, cardDetailedText, media, url, date, timelineContent, items (for nested timelines), and more.

mode

Type: 'HORIZONTAL' | 'VERTICAL' | 'VERTICAL_ALTERNATING'
Default: 'HORIZONTAL'

Sets the layout mode of the timeline. Changed to HORIZONTAL from VERTICAL_ALTERNATING for new projects.

theme

Type: Theme
Default: {...}

Enhanced theming with 15+ new dark mode properties for complete visual customization. See Theming & Styling for details.

Layout & Sizing

cardHeight

Type: number
Default: 200

Minimum height (in pixels) of timeline cards.

cardWidth

Type: number
Default: 450

Maximum width (in pixels) of timeline cards.

itemWidth

Type: number
Default: 200

Width (in pixels) of each timeline section in HORIZONTAL mode.

contentDetailsHeight

Type: number
Default: 150

Height (in pixels) of the detailed content area within a card if cardDetailedText is used.

lineWidth

Type: number
Default: 3

Width (in pixels) of the main timeline track line.

timelinePointDimension

Type: number
Default: 16

Diameter (in pixels) of the circular points on the timeline.

nestedCardHeight

Type: number
Default: 150

Height (in pixels) of cards within a nested timeline.

scrollable

Type: boolean | { scrollbar: boolean }
Default: { scrollbar: false }

Makes VERTICAL and VERTICAL_ALTERNATING modes scrollable. Set to { scrollbar: true } to show the scrollbar.

enableBreakPoint

Type: boolean
Default: true

If true, VERTICAL_ALTERNATING mode automatically switches to VERTICAL mode when responsiveBreakPoint is reached.

responsiveBreakPoint

Type: number
Default: 768

Viewport width (in pixels) at which VERTICAL_ALTERNATING mode switches to VERTICAL if enableBreakPoint is true.

cardPositionHorizontal

Type: 'TOP' | 'BOTTOM'

Positions the card above or below the timeline in HORIZONTAL mode.

flipLayout

Type: boolean
Default: false

Reverses the layout direction (e.g., Right-to-Left for horizontal, or swaps sides for vertical alternating).

showAllCardsHorizontal

Type: boolean
Default: false

In HORIZONTAL mode, displays all cards simultaneously instead of only the active one.

Navigation & Interaction

disableNavOnKey

Type: boolean
Default: false

Disables keyboard navigation (LEFT/RIGHT for Horizontal, UP/DOWN for Vertical).

disableClickOnCircle

Type: boolean
Default: false

Disables click action on timeline points/circles.

disableAutoScrollOnClick

Type: boolean
Default: false

Prevents auto-scrolling to the active card when a timeline card or point is clicked.

onItemSelected

Type: function

Callback function invoked when a timeline item is selected. Passes item data and index.

onScrollEnd

Type: function

Callback function invoked when the end of the timeline is reached during scrolling.

focusActiveItemOnLoad

Type: boolean
Default: false

Automatically scrolls to and focuses on the activeItemIndex when the timeline loads.

disableInteraction

Type: boolean
Default: false

Disables all user interactions with the timeline (clicks, keyboard navigation).

enableQuickJump

Type: boolean
Default: true

Allows quick jumping to a timeline item via controls (if toolbar is enabled).

useReadMore

Type: boolean
Default: true

Enables a "read more" button if card content exceeds available space. Set to false to always show all text.

semanticTags

Type: SemanticTagsConfig

Configure semantic HTML tags for card elements to improve accessibility and SEO.

interface SemanticTagsConfig {
  cardTitle?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'span' | 'div';
  cardSubtitle?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'span' | 'div';
}

Media Handling

mediaSettings

Type: { align?: 'left' | 'right' | 'center'; fit?: 'cover' | 'contain' | 'fill' | 'none' | 'scale-down' }
Default: { align: 'left', fit: 'cover' }

Controls global media display alignment and CSS object-fit property for images.

Content & Display

borderLessCards

Type: boolean
Default: false

Removes borders and shadows from timeline cards for a flatter look.

cardLess

Type: boolean
Default: false

Hides timeline cards, showing only titles/points. Useful for a very compact timeline.

disableTimelinePoint

Type: boolean
Default: false

Hides the circular points on the timeline track.

timelinePointShape

Type: 'circle' | 'square' | 'diamond'
Default: 'circle'

Configures the shape of the points on the timeline.

textOverlay

Type: boolean
Default: false

Displays text content as an overlay on top of media elements. Requires text property in timeline items.

parseDetailsAsHTML

Type: boolean
Default: false

If true, cardDetailedText will be parsed as HTML. Use with caution due to XSS risks if content is user-supplied.

titleDateFormat

Type: string
Default: 'MMM DD, YYYY'

Date format for item titles when using the date property in items. Supports all day.js formats.

textDensity

Type: 'LOW' | 'HIGH'
Default: 'HIGH'

Configures the amount of text displayed in cards. 'LOW' might truncate more aggressively.

Slideshow

slideShow

Type: boolean
Default: false

Enables slideshow mode and shows play/pause controls in the toolbar.

slideItemDuration

Type: number
Default: 2500

Duration (in milliseconds) each timeline item remains active during a slideshow.

slideShowType

Type: 'reveal' | 'slide_from_sides' | 'slide_in'

Type of animation for slideshow transitions. Defaults: VERTICAL -> 'reveal', VERTICAL_ALTERNATING -> 'slide_from_sides', HORIZONTAL -> 'slide_in'.

showOverallSlideshowProgress

Type: boolean
Default: true (when slideShow is enabled)

Shows a line-based progress bar at the top of the screen during slideshow mode, indicating overall progress across all timeline items.

Search

searchPlaceholder

Type: string
Default: "Search..."

Placeholder text for the search input in the toolbar.

searchAriaLabel

Type: string
Default: "Search timeline"

ARIA label for the search input for accessibility.

clearSearch

Type: string
Default: "Clear search"

Text/ARIA label for the clear search button.

Theming & Styling

enableDarkToggle

Type: boolean
Default: false

Adds a toggle switch to the toolbar for enabling dark mode (if dark theme is configured).

onThemeChange

Type: function

Callback invoked when the theme changes, e.g., via the dark mode toggle. Passes the new theme object.

fontSizes

Type: { cardSubtitle?: string; cardText?: string; cardTitle?: string; title?: string; }

Adjust font sizes for card elements.

buttonTexts

Type: ButtonTexts

Customize button text and accessibility labels for all interactive elements.

classNames

Type: { card?: string; cardMedia?: string; cardSubTitle?: string; cardText?: string; cardTitle?: string; controls?: string; title?: string; }

Apply custom CSS classes to various parts of the timeline.

highlightCardsOnHover

Type: boolean
Default: false

Highlights timeline cards on mouse hover.

Miscellaneous

noUniqueId

Type: boolean
Default: false

Prevents generating a unique ID for the timeline wrapper. Use with uniqueId if you need to set a specific ID.

uniqueId

Type: string

Sets a custom unique ID for the timeline wrapper. Useful with noUniqueId={true}.

disableToolbar

Type: boolean
Default: false

Hides the entire toolbar/control panel.

toolbarPosition

Type: 'top' | 'bottom'
Default: 'top'

Positions the toolbar at the top or bottom of the timeline.

enableLayoutSwitch

Type: boolean
Default: true

Enables the layout switcher for the timeline. Switches the vertical timeline to vertical_alternating and vice versa. Switches the horizontal timeline to horizontal_all and vice versa.

This property sets the dimensions of the circular points on the timeline.

useReadMore

Enabling this property displays the "read more" button, which is only available if the text content on the card is taller than the card itself.

fontSizes

This property is used to customize the font sizes.

buttonTexts

This property is used to customize the alt text for all buttons.

highlightCardsOnHover

Enabling this property highlights the timeline card on hover.

disableInteraction

Enabling this property disables all interactions with the timeline.

parseDetailsAsHTML

Enabling this property parses the details text as HTML.

toolbarPosition

This property sets the position of the toolbar. The value can be either TOP or BOTTOM.

enableBreakPoint

Enabling this property enables the breakpoint for the timeline. This only applies for the vertical and vertical_alternating mode.

responsiveBreakPoint

Responsive breakpoint in pixels. This only applies for the vertical and vertical_alternating mode. This works only if the enableBreakPoint is set to true.

enableLayoutSwitch

Enabling this property enables the layout switcher for the timeline. Switches the vertical timeline to vertical_alternating and vice versa. Switches the horizontal timeline to horizontal_all and vice versa.

enableQuickJump

Enabling this property enables the quick jump feature for the timeline. When enabled, the user can jump to a specific timeline item.

disableToolbar

Enabling this property disables and hide the toolbar.