@d3-timeline/astro

An Astro component wrapper for the D3-based Timeline visualization component. It seamlessly integrates the framework-agnostic D3 timeline logic with Astro's template engine and slot mechanisms.

Installation

npm install @d3-timeline/astro @d3-timeline/core

Basic Usage

Import the Timeline and TimelineItem components into your .astro page. Then, pass your array of event objects as well as a configuration object. The timeline elements will initialize correctly on the client side when the page loads.

---
import Timeline from '@d3-timeline/astro';
import TimelineItem from '@d3-timeline/astro/TimelineItem.astro';

const events = [
  { id: "1", date: new Date("2023-01-15"), title: "Project Kickoff", description: "Initial team meeting." },
  { id: "2", date: new Date("2023-05-10"), title: "Alpha Release", description: "First working version." }
];

const config = {
  orientation: 'horizontal' // 'horizontal' or 'vertical'
};
---

<div style="height: 400px; position: relative;">
  <Timeline data={events} config={config}>
    {events.map((item) => (
      <TimelineItem id={item.id}>
        <div class="custom-event-card">
          <h3>{item.title}</h3>
          <p>{item.description}</p>
          <small>{item.date.toDateString()}</small>
        </div>
      </TimelineItem>
    ))}
  </Timeline>
</div>

<style>
.custom-event-card {
  background: white;
  border: 1px solid #ccc;
  padding: 10px;
  border-radius: 4px;
}
</style>

Props (<Timeline>)

• data: An array of data objects. Each object must contain a valid date property (JavaScript Date object).
• config: A configuration object passed down to the core engine. You can configure orientation, custom collisionPriority, etc.

Props (<TimelineItem>)

• id: A unique identifier (string or number) matching the id from your data array element. This is required for the timeline core to pair your rendered DOM nodes with their exact temporal placement.

Client-side Events

Because Astro is primarily a static HTML builder, reactivity requires interacting with standard DOM events. The timeline container element emits a timeline-selected Custom Event when an item is clicked.

<script>
  document.addEventListener('timeline-selected', (e) => {
    console.log('User selected:', e.detail);
  });
</script>