Flash Calendar Documentation

Flash Calendar follows a "bring your own date library" approach.

Simple Localization

Use calendarFormatLocale to pass a locale string (e.g., 'pt-BR').

Full Customization

Use the following props to provide custom formatting functions (compatible with libraries like date-fns):

• getCalendarDayFormat
• getCalendarMonthFormat
• getCalendarWeekDayFormat

CRITICAL: Referential Equality To prevent performance issues and unnecessary re-renders, formatting functions must be stable. Do not define them inline inside the component. Instead, define them outside the component scope or wrap them in useCallback.

import { Calendar, toDateId } from "@marceloterreiro/flash-calendar";
import { subMonths } from "date-fns";
import { format } from "date-fns/fp";

const threeMonthsAgo = subMonths(new Date(), 3);

export const CalendarCustomFormatting = () => {
  return (
    <Calendar
      calendarMonthId={toDateId(threeMonthsAgo)}
      getCalendarDayFormat={format("dd")}
      getCalendarMonthFormat={format("MMMM yyyy (LL/yyyy)")}
      getCalendarWeekDayFormat={format("E")}
      onCalendarDayPress={(dateId) => {
        console.log(`Clicked on ${dateId}`);
      }}
    />
  );
};

The Flash Calendar is composed of several hierarchical components. Understanding this structure is essential for both styling via the theme prop and for composing custom calendars.

Currently, Flash Calendar's infinite scrolling does not work backwards. While onEndReached allows appending new months as the user scrolls forward, there is no onStartReached implementation to prepend months while maintaining scroll position. Consequently, the calendar will not scroll past the initial month when scrolling upwards.

To enable backward scrolling, you can preload the required range of past months using calendarMinDateId and calendarPastScrollRangeInMonths.

Note on Performance: Preloading a large number of months increases memory usage because the month list is held in memory. However, due to the efficiency of Flash List, rendering a large number of months (e.g., 2,000 months/166 years) is generally performant.

export const ScrollingBackwardsWorkaround = () => {
  return (
    <VStack alignItems="stretch" grow spacing={12}>
      <Text>This preloads all past months between Jan 1st 2020 and today</Text>

      <Calendar.List
        calendarFutureScrollRangeInMonths={1}
        calendarInitialMonthId="2024-02-01"
        calendarMaxDateId="2024-05-01"
        calendarMinDateId="2020-01-01"
        calendarPastScrollRangeInMonths={50}
        onCalendarDayPress={loggingHandler("onCalendarDayPress")}
      />
    </VStack>
  );
};

When using calendarActiveDateRanges in <Calendar.List />, improper state management can cause the entire list to re-render whenever the ranges change, leading to frame drops.

Recommended Solutions:

1. Use useDateRange: The easiest and most optimized way to handle date ranges is to use the built-in useDateRange hook.
2. Manual Implementation: If you must manually control onCalendarDayPress, you must ensure performance by:
   • Memoizing the onCalendarDayPress function using useCallback.
   • Using the updater function pattern (e.g., setDates(prev => ... )) when updating state. This keeps the props of the underlying BaseCalendar components stable, preventing unnecessary re-renders of every month in the list.

import type { CalendarOnDayPress } from "@marceloterreiro/flash-calendar";
import { Calendar, toDateId } from "@marceloterreiro/flash-calendar";
import { addMonths } from "date-fns";
import { useCallback, useState } from "react";
import { Text } from "react-native";

const todayId = toDateId(new Date());
const maxDateId = toDateId(addMonths(new Date(), 12));

export const SlowExampleAddressed = () => {
  const [dateIds, setDateIds] = useState<string[]>([]);
  const dateRanges = dateIds.map((dateId) => ({
    startId: dateId,
    endId: dateId,
  }));

  // This is the fix: memoized onCalendarDayPress and updater function pattern
  // It keeps `BaseCalendar` props stable, allowing each month to skip re-renders
  const handleCalendarDayPress = useCallback<CalendarOnDayPress>((dateId) => {
    setDateIds((dateIds) => {
      if (dateIds.includes(dateId)) {
        return dateIds.filter((id) => id !== dateId);
      } else {
        return [...dateIds, dateId];
      }
    });
  }, []);

  return (
    <Calendar.VStack alignItems="stretch" grow spacing={12}>
      <Text>✅ This is safe to copy, perf issues addressed</Text>

      <Calendar.List
        calendarActiveDateRanges={dateRanges}
        calendarInitialMonthId={todayId}
        calendarMaxDateId={maxDateId}
        calendarMinDateId={todayId}
        onCalendarDayPress={handleCalendarDayPress}
      />
    </Calendar.VStack>
  );
};

To use Calendar.List inside a component like react-native-bottom-sheet (especially on Android), you can replace the default scroll component by passing a custom component to the CalendarScrollComponent prop.

import BottomSheet from "@gorhom/bottom-sheet";
import { Calendar } from "@marceloterreiro/flash-calendar";
import { FlashList } from "@shopify/flash-list";
import React, { useMemo, useRef } from "react";
import { Platform, StyleSheet, View } from "react-native";

// Note: Implementation of BottomSheetFlashList is required for Android
const SafeFlashList = Platform.select({
  android: BottomSheetFlashList,
  ios: FlashList,
});

export const BottomSheetCalendar = () => {
  const bottomSheetRef = useRef<BottomSheet>(null);
  const snapPoints = useMemo(() => ["25%", "50%"], []);

  return (
    <View style={styles.container}>
      <BottomSheet index={1} ref={bottomSheetRef} snapPoints={snapPoints}>
        <View style={styles.contentContainer}>
          <Calendar.List
            CalendarScrollComponent={SafeFlashList}
            calendarInitialMonthId="2024-02-01"
            onCalendarDayPress={(dateId) => console.log(`Pressed ${dateId}`)}
          />
        </View>
      </BottomSheet>
    </View>
  );
};

To support web interactions (like Pressable interaction states in react-native-web), you can use isHovered and isFocused within your CalendarTheme style functions for itemDay states (idle and today).

const linearTheme: CalendarTheme = {
  // ... other theme properties
  itemDay: {
    idle: ({ isPressed, isHovered, isWeekend }) => ({
      container: {
        backgroundColor: isPressed || isHovered ? linearAccent : "transparent",
        borderRadius: 4,
      },
      content: {
        color: isWeekend && !isPressed ? "rgba(255, 255, 255, 0.5)" : "#ffffff",
      },
    }),
    today: ({ isPressed, isHovered }) => ({
      container: {
        borderColor: "rgba(255, 255, 255, 0.5)",
        borderRadius: isPressed || isHovered ? 4 : 30,
        backgroundColor: isPressed || isHovered ? linearAccent : "transparent",
      },
      content: {
        color: isPressed || isHovered ? "#ffffff" : "rgba(255, 255, 255, 0.5)",
      },
    }),
    // ...
  },
};