@memberjunction/ng-timeline

A powerful, flexible Angular timeline component with zero external dependencies. Works with both MemberJunction BaseEntity objects and plain JavaScript objects. Pure HTML/CSS implementation with virtual scrolling, time-segment grouping, and full keyboard accessibility.

Installation

npm install @memberjunction/ng-timeline

Overview

The timeline renders chronologically ordered events as cards along a vertical or horizontal axis. Events can be grouped by time segments (day, week, month, quarter, year) with collapsible sections. The component uses a BeforeX/AfterX event pattern that allows container components to intercept and cancel default behaviors.

flowchart TD
    subgraph Data["Data Sources"]
        A["Plain JS Objects"]
        B["MJ BaseEntity Objects"]
    end
    subgraph Config["TimelineGroup Config"]
        C["Field Mappings"]
        D["Display Options"]
        E["Card Config"]
    end
    subgraph Component["TimelineComponent"]
        F["Time Segments"]
        G["Event Cards"]
        H["Virtual Scroll"]
        I["Keyboard Nav"]
    end

    A --> Config
    B --> Config
    Config --> Component

    style Data fill:#2d6a9f,stroke:#1a4971,color:#fff
    style Config fill:#7c5295,stroke:#563a6b,color:#fff
    style Component fill:#2d8659,stroke:#1a5c3a,color:#fff

Usage

Module Import

import { TimelineModule } from '@memberjunction/ng-timeline';

@NgModule({
  imports: [TimelineModule]
})
export class YourModule {}

With Plain Objects

import { TimelineGroup } from '@memberjunction/ng-timeline';

interface MyEvent {
  id: string;
  title: string;
  eventDate: Date;
  description: string;
}

const group = TimelineGroup.FromArray(myEvents, {
  titleField: 'title',
  dateField: 'eventDate',
  descriptionField: 'description'
});

<mj-timeline [groups]="[group]"></mj-timeline>

With MemberJunction Entities

const group = new TimelineGroup<TaskEntity>();
group.EntityName = 'Tasks';
group.DataSourceType = 'entity';
group.Filter = "Status = 'Open'";
group.TitleFieldName = 'Name';
group.DateFieldName = 'DueDate';

Key Inputs

Input	Type	Default	Description
groups	TimelineGroup<T>[]	[]	Data groups to display
orientation	'vertical' | 'horizontal'	'vertical'	Timeline axis
layout	'single' | 'alternating'	'single'	Card layout
sortOrder	'asc' | 'desc'	'desc'	Event sort order
segmentGrouping	'none' | 'day' | 'week' | 'month' | 'quarter' | 'year'	'month'	Time grouping
segmentsCollapsible	boolean	true	Allow collapsing segments
enableKeyboardNavigation	boolean	true	Keyboard support
virtualScroll	VirtualScrollConfig	—	Virtual scroll settings

Event System (BeforeX/AfterX Pattern)

Every user interaction emits a “before” event (cancelable) and an “after” event:

Before Event	After Event	Description
beforeEventClick	afterEventClick	Card clicked
beforeEventExpand	afterEventExpand	Card expanded
beforeEventCollapse	afterEventCollapse	Card collapsed
beforeActionClick	afterActionClick	Action button clicked
beforeSegmentExpand	afterSegmentExpand	Segment expanded
beforeSegmentCollapse	afterSegmentCollapse	Segment collapsed
beforeLoad	afterLoad	Data loaded

onBeforeClick(args: BeforeEventClickArgs<MyType>) {
  if (args.event.entity.status === 'archived') {
    args.cancel = true;  // Prevent default behavior
  }
}

Custom Templates

Override card rendering with Angular templates:

<mj-timeline [groups]="groups">
  <ng-template #cardTemplate let-event="event">
    <div class="custom-card">{{ event.title }}</div>
  </ng-template>
  <ng-template #emptyTemplate>
    <p>No events found.</p>
  </ng-template>
</mj-timeline>

Available template refs: cardTemplate, headerTemplate, bodyTemplate, actionsTemplate, segmentHeaderTemplate, emptyTemplate, loadingTemplate

Theming (CSS Variables)

mj-timeline {
  --mj-timeline-line-color: #e0e0e0;
  --mj-timeline-marker-bg: #1976d2;
  --mj-timeline-card-bg: #ffffff;
  --mj-timeline-card-border: #e0e0e0;
  --mj-timeline-text-primary: #212121;
  --mj-timeline-accent: #1976d2;
  --mj-timeline-card-max-width: 400px;
}

Keyboard Navigation

Key	Action
Arrow Down/Right	Next event
Arrow Up/Left	Previous event
Enter/Space	Toggle expand/collapse
Escape	Collapse focused event
Home/End	Jump to first/last event

Dependencies

No external UI library dependencies. Pure Angular + HTML/CSS implementation.

• @memberjunction/core — Optional, for entity data sources
• @memberjunction/core-entities — Optional, for entity types