Skip to main content
CalendarList extends the Calendar component to display multiple months in a scrollable list, supporting both horizontal and vertical scrolling.

​
Basic usage

import { CalendarList } from 'react-native-calendars';

<CalendarList
  onDayPress={(day) => console.log('selected day', day)}
  markedDates={{
    '2023-05-16': {selected: true}
  }}
/>

​
Props

CalendarList extends all Calendar props with additional list-specific properties.

​
Scroll configuration

​
pastScrollRange
number
default:"50"
Maximum amount of months allowed to scroll to the past.
​
futureScrollRange
number
default:"50"
Maximum amount of months allowed to scroll to the future.
​
scrollEnabled
boolean
default:"true"
Enable or disable scrolling of the calendar list.
​
showScrollIndicator
boolean
default:"false"
Enable or disable vertical/horizontal scroll indicator.
​
animateScroll
boolean
default:"false"
Whether to animate the auto month scroll.
​
scrollsToTop
boolean
default:"false"
Enable scrolling to top when tapping on status bar (iOS only).
​
nestedScrollEnabled
boolean
default:"true"
Enable nested scrolling for Android.

​
Layout configuration

​
horizontal
boolean
default:"false"
Whether to render the calendar list horizontally. When true, pagination should be disabled.
​
pagingEnabled
boolean
Enable paging on horizontal calendar list.
​
calendarWidth
number
Used when calendar scroll is horizontal. Default is device width. Pagination should be disabled when using this prop.
​
calendarHeight
number
default:"360"
Dynamic calendar height for vertical scrolling.
​
calendarStyle
ViewStyle
Style for the List item (the individual calendar).
calendarStyle={{
  borderWidth: 1,
  borderColor: 'gray',
  height: 350
}}
​
staticHeader
boolean
Use static header that will not scroll with the list (horizontal only).

​
FlatList props

CalendarList also supports the following FlatList props:
​
removeClippedSubviews
boolean
Remove clipped subviews to improve performance.
​
contentContainerStyle
ViewStyle
Style for the FlatList content container.
​
keyExtractor
(item: any, index: number) => string
Used to extract a unique key for a given item at the specified index.
​
keyboardShouldPersistTaps
'never' | 'always' | 'handled'
Determines when the keyboard should stay visible after a tap.
​
onEndReachedThreshold
number
How far from the end (in units of visible length) the bottom edge of the list must be from the end of the content to trigger the onEndReached callback.
​
onEndReached
(info: {distanceFromEnd: number}) => void
Called once when the scroll position gets within onEndReachedThreshold of the rendered content.

​
Scroll event handlers

​
onScrollBeginDrag
(event: NativeSyntheticEvent<NativeScrollEvent>) => void
Called when the user begins dragging the calendar list.
​
onScrollEndDrag
(event: NativeSyntheticEvent<NativeScrollEvent>) => void
Called when the user stops dragging the calendar list.
​
onMomentumScrollBegin
(event: NativeSyntheticEvent<NativeScrollEvent>) => void
Called when the momentum scroll starts.
​
onMomentumScrollEnd
(event: NativeSyntheticEvent<NativeScrollEvent>) => void
Called when the momentum scroll stops.

​
Other props

​
onLayout
(event: LayoutChangeEvent) => void
Invoked on mount and layout changes.
​
onHeaderLayout
(event: LayoutChangeEvent) => void
Callback for header layout events.

​
Imperative methods

You can call these methods on the CalendarList ref:

​
scrollToDay

scrollToDay(date: XDate | string, offset: number, animated: boolean): void
Scroll to a specific day with optional offset and animation. 
import { useRef } from 'react';
import { CalendarList } from 'react-native-calendars';

function MyCalendar() {
  const calendarRef = useRef(null);

  const scrollToToday = () => {
    calendarRef.current?.scrollToDay(new Date(), 0, true);
  };

  return <CalendarList ref={calendarRef} />;
}

​
scrollToMonth

scrollToMonth(date: XDate | string): void
Scroll to a specific month. 
const scrollToNextMonth = () => {
  const nextMonth = new Date();
  nextMonth.setMonth(nextMonth.getMonth() + 1);
  calendarRef.current?.scrollToMonth(nextMonth);
};

​
Examples

​
Horizontal calendar list

<CalendarList
  horizontal
  pagingEnabled
  calendarWidth={320}
  onDayPress={(day) => console.log('selected day', day)}
/>

​
Vertical calendar list with custom range

<CalendarList
  pastScrollRange={12}
  futureScrollRange={12}
  scrollEnabled={true}
  showScrollIndicator={true}
  onDayPress={(day) => console.log('selected day', day)}
/>

​
Calendar list with static header

<CalendarList
  horizontal
  pagingEnabled
  staticHeader
  calendarStyle={{
    borderWidth: 1,
    borderColor: 'gray',
    margin: 10
  }}
/>

​
Scrollable calendar with custom styling

<CalendarList
  calendarHeight={390}
  calendarStyle={{
    backgroundColor: '#f5f5f5',
    paddingBottom: 20
  }}
  theme={{
    backgroundColor: '#ffffff',
    calendarBackground: '#ffffff',
    selectedDayBackgroundColor: '#00adf5',
    selectedDayTextColor: '#ffffff'
  }}
/>

​
Notes

When using horizontal mode with custom calendarWidth, make sure to disable pagingEnabled or set it explicitly to control the scrolling behavior.
Setting very large values for pastScrollRange and futureScrollRange can impact performance, especially on lower-end devices.

Build docs developers (and LLMs) love

Get started for freeTalk to us