React Native Timeline Calendar

A customizable, Google Calendar-inspired timeline component for React Native that displays events across a 24-hour period. The component features a sleek dark theme by default with customizable styling options.

Installation

npm install @touchblack/timeline-calendar

Peer Dependencies

This package requires the following peer dependencies:

npm install react react-native

Features

• Complete 24-hour timeline display (00:00 - 23:59)
• Event visualization with customizable time spans
• Smart handling of overlapping events
• Current time indicator that shows the present moment
• Dark theme by default with customizable colors
• Auto-scrolling to current time
• Event interaction support
• Performant rendering even with many events

Usage

import React, { useState } from 'react';
import { View, Alert } from 'react-native';
import TimelineCalendar from '@touchblack/timeline-calendar';

const MyCalendarScreen = () => {
  const [events, setEvents] = useState([
    { 
      id: 1, 
      title: 'Team Meeting', 
      start: '09:00', 
      end: '10:30', 
      color: '#E9BF99' 
    },
    { 
      id: 2, 
      title: 'Lunch Break', 
      start: '12:00', 
      end: '13:00', 
      color: '#9E7653' 
    },
    // Add more events as needed
  ]);

  const handleEventPress = (event) => {
    Alert.alert(
      event.title,
      `${event.start} - ${event.end}`,
      [{ text: 'OK' }]
    );
  };

  const handleAddEvent = () => {
    // Logic to add a new event
    const newEvent = {
      id: events.length + 1,
      title: 'New Event',
      start: '14:00',
      end: '15:30',
      color: '#C29B73'
    };
    
    setEvents([...events, newEvent]);
  };

  return (
    <View style={{ flex: 1 }}>
      <TimelineCalendar 
        events={events}
        onEventPress={handleEventPress}
        onAddEvent={handleAddEvent}
      />
    </View>
  );
};

export default MyCalendarScreen;

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | events | Array | [] | Array of event objects with format { id, title, start, end, color } | | onEventPress | Function | - | Callback function when an event is pressed, receives the event object as parameter | | onAddEvent | Function | - | Callback function when the add event button is pressed | | primaryColor | String | '#E9BF99' | Primary color for the component (events, current time indicator) | | backgroundColor | String | '#121212' | Background color of the calendar | | textColor | String | '#FFFFFF' | Main text color | | secondaryTextColor | String | '#AAAAAA' | Secondary text color (used for time labels) | | hourHeight | Number | 60 | Height in pixels for each hour in the timeline |

Event Object Format

Each event in the events array should have the following properties:

{
  id: 1,                 // Unique identifier for the event
  title: 'Event Title',  // Title of the event
  start: '09:00',        // Start time in 24-hour format (HH:MM)
  end: '10:30',          // End time in 24-hour format (HH:MM)
  color: '#E9BF99'       // Color for the event (optional, uses primaryColor if not specified)
}

Customization Examples

Custom Colors

<TimelineCalendar 
  events={events}
  primaryColor="#FF5733"
  backgroundColor="#000000"
  textColor="#FFFFFF"
  secondaryTextColor="#BBBBBB"
/>

Adjust Timeline Density

<TimelineCalendar 
  events={events}
  hourHeight={80} // Taller hours for more space
/>

Advanced Usage

Refreshing the Current Time Indicator

For a continuously updating current time indicator, you can use a timer to refresh the component:

import React, { useState, useEffect } from 'react';
import { View } from 'react-native';
import TimelineCalendar from '@touchblack/timeline-calendar';

const LiveUpdatingCalendar = () => {
  const [refreshKey, setRefreshKey] = useState(0);
  
  useEffect(() => {
    // Update every minute
    const intervalId = setInterval(() => {
      setRefreshKey(prevKey => prevKey + 1);
    }, 60000);
    
    return () => clearInterval(intervalId);
  }, []);
  
  return (
    <View style={{ flex: 1 }}>
      <TimelineCalendar 
        key={refreshKey}
        events={events} 
      />
    </View>
  );
};

Performance Considerations

When working with many events, keep these tips in mind:

1. Memoize event handlers to prevent unnecessary re-renders
2. Use unique and stable IDs for your events
3. Limit the number of events displayed at once when possible

Troubleshooting

Events not displaying correctly

Ensure your event times are in the correct format (HH:MM). The component expects times in 24-hour format.

Current time indicator not accurate

The current time indicator is set when the component mounts. For a continuously updating indicator, use the refresh approach shown in the advanced usage section.