Skip to content

Timeline Controls

Control the Timeline component using methods and properties exposed through a forwarded ref.

Properties

Section titled “Properties”
PropertyTypeDescription
dataArrayGet or set timeline items
align'left' | 'right' | 'top' | 'bottom'Position of timeline bullets
order'asc' | 'desc'Sort order of items
type'default' | 'monthly'Timeline view type

Methods

Section titled “Methods”
MethodDescription
refresh()Refresh the display
goToMonth(year, month)Navigate to month (monthly view)
goToToday()Navigate to current month
nextMonth()Navigate to next month
previousMonth()Navigate to previous month

Example

Section titled “Example”
import { useRef } from 'react';
import { Timeline } from '@calendarjs/react';

export default function App() {
    const timelineRef = useRef();
    const data = [
        { title: 'Event 1', date: '2025-01-01' },
        { title: 'Event 2', date: '2025-02-01' },
        { title: 'Event 3', date: '2025-03-01' }
    ];

    return (
        <div>
            <select onChange={(e) => timelineRef.current.align = e.target.value}>
                <option value="left">Left</option>
                <option value="right">Right</option>
            </select>
            <select onChange={(e) => timelineRef.current.order = e.target.value}>
                <option value="asc">Ascending</option>
                <option value="desc">Descending</option>
            </select>
            <Timeline ref={timelineRef} data={data} />
        </div>
    );
}

With useTimeline

Section titled “With useTimeline”

The hook returns a callback ref plus a reactive instance — buttons can be disabled until the timeline has mounted:

import { useState } from 'react';
import { Timeline, useTimeline } from '@calendarjs/react';

export default function App() {
    const { ref, instance } = useTimeline();
    const [data] = useState([
        { title: 'Event 1', date: '2025-01-01' },
        { title: 'Event 2', date: '2025-02-01' },
        { title: 'Event 3', date: '2025-03-01' },
    ]);

    return (
        <>
            <div style={{ display: 'flex', gap: 8 }}>
                <button disabled={!instance} onClick={() => instance.prev()}>Previous month</button>
                <button disabled={!instance} onClick={() => instance.next()}>Next month</button>
            </div>

            <Timeline ref={ref} type="monthly" value="2025-01-01" data={data} />
        </>
    );
}
Section titled “Related”