API_REFERENCE.md

API Reference

Calendar Props

Our Calendar component has a list of props that make it easy to plug and play UI for your calendars.

Prop	Type	Description	Default
contentContainerStyle	ViewStyle?	ViewStyle` for calendar's parent view component	undefined
customStateCreator	((stateInputParams: StateInputParams, defaultState?: DayState) => object)?	Function for extending/customizing calendar day state ⚠️Caution: Always use a pure named function for optimal performance. See example here	undefined
DayComponent	React.ComponentType<InnerDayProps<T>>	Custom component to render each day of month on the calendar; _⚠️Caution: Always use a pure named component for optimal performance. See example here	undefined
firstDayOfWeek	DayIndex?	DayIndex which is used to determine the first day of the week for this date according to local time, where 0 represents Sunday	0
locale	string?	Locale string used to localize calendar content	en-US
markedDates	string[]	Selected day(s) on the calendar to be highlighted Format [YYYY-MM-DD,...]	[]
maxDate	string?	Maximum selectable date on the calendar example: 2024-12-31 Format YYYY-MM-DD	undefined
minDate	string?	Minimum selectable date on the calendar example: 2024-01-01 Format YYYY-MM-DD	undefined
MonthAnimatedTransitionComponent	React.ComponentType<{ React.PropsWithChildren }>?	Custom component to wrap monthly calendar view useful when you need to animate entry and exit transitions of monthly calendar component during toggle of viewAs	React.Fragment
MonthNameComponent	React.ComponentType<{ month: Date; locale?: string }>	Custom component to render calendar's month title; example: August, 2024	undefined
onDayPress	((dateString: string) => void)?	Function for adding press listener to calendar day ⚠️ Caution: Always use a pure named function for optimal performance. See example here	undefined
showDayNames	boolean?	Show week day names on the calendar	true
showExtraDays	boolean?	Show extra days from previous and next month in the current month's calendar	true
showMonthName	boolean?	Show calendar's month title	true
viewAs	<"week","month">?	Toggle calendar view between weeks list or full month	month
WeekAnimatedTransitionComponent	React.ComponentType<{ React.PropsWithChildren }>?	Custom component to wrap weekly calendar view useful when you need to animate entry and exit transitions of weekly calendar component during toggle of viewAs	React.Fragment
weekContainerStyle	ViewStyle?	ViewStyle for each week row on the calendar	undefined
WeekDayNameComponent	React.ComponentType<{ weekDays:string[] }>	Custom component to render calendar's week day names	undefined
weekdaysFormat	<"long","short","narrow"> short = ['Mon', 'Tue', ..., 'Sun'] long = ['Monday', 'Tuesday', ..., 'Sunday'] narrow = ['M', 'T', ..., 'S']	Format option for week day names	undefined
weekdaysShort	string[]?	Custom names for week days ⚠️Caution: This overrides the default localized week day names	undefined
weeksContainerStyle	ViewStyle?	ViewStyle for parent view component of all week rows on the calendar. Useful when you need to apply styling to all weeks in the calendar	undefined

CalendarList Props

CalendarList inherits all props of Calendar except contentContainerStyle & date props. It also comes with unique props to help you build performant list of calendars whiles using @shopify/flashlist under the hood.

Prop	Type	Description	Default
calendarContentContainerStyle	ViewStyle?	ViewStyle for each calendar's parent view component. This is same as contentContentContainerStyle prop for Calendar component	undefined
CalendarSeparator	React.ComponentType?	A component rendered between calendars in the list ⚠️ Caution: This overrides the default calendarVerticalGap when defined	undefined
calendarSize	{width?:number, height?: number}?	Visible width and height of the CalendarList. This is not the scroll content size.	{ width, height } = Dimensions.get("window")
calendarVerticalGap	number?	Space (px) between calendars in the list ⚠️ Caution: Use the height of CalendarSeparator when it is defined	32
currentDate	string?	Initial date to focus or scroll to when the CalendarList mounts ⚠️Caution: This prop is not reactive, changing it will not trigger re-render Format YYYY-MM-DD	undefined
estimatedCalendarSize	{fiveWeekCalendarSize: number, monthTitleSize?: number, weekDayNamesSize?: number}	fiveWeekCalendarSize is height of each calendar when using vertical calendar lists, this is required. monthTitleSize is height of the MonthNameComponent component weekDayNamesSize is the height of the WeekDayNameComponent It is recommended to provide a accurate value if you use custom components for weekDayNames and/or monthTitle. 💡 FlashList uses this information to decide how many calendar months it needs to draw on the screen before initial load and while scrolling. Since calendar months have 5 and 6 weeks, you need to find the height of a month with five weeks, and use that number as fiveWeekCalendarSize. A quick look at Element Inspector can help you determine this. See understanding calendar components	required
futureMonthsCount	number?	Number of months to render after minDate	12
horizontal	boolean?	Toggle horizontal scrollable list	false
minDate	string?	Date in your starred month on the calendar. A starred month is the month in calendar list used to determined past and future months of the list. Example: If you need to render daily events 6 months before and after date 2024-02-10. Then 2024-02 becomes the starred month Format YYYY-MM-DD	today's date
onActiveMonthChange	((activeMonthDatestring: string) => void)?	Callback to get the first visible month of the calendar list; param is a date string. This is useful when you only need the first visible month for rendering Format YYYY-MM-DD	undefined
onEndReachedThreshold	number?	How far from the end (in units of visible length of the list) the trailing edge of the list must be from the end of the content to trigger the onEndReached callback. Thus, a value of 0.5 will trigger onEndReached when the end of the content is within half the visible length of the list.	2
onListEndReached	(() => void)?	Callback for calendar list scroll reach end of list event.	undefined
onScroll	((visibleMonths: string[]) => void)?	Callback for calendar list scroll events; param is an array of visible months on the list ordered according to appearance on the list. Format [YYYY-MM-DD,...]	undefined
pastMonthsCount	number?	Number of months to render before minDate	0
showDayNamesOnTop	boolean?	Show week day names on top of list instead of in each calendar	false
showScrollIndicator	boolean?	Toggle on scroll indicators for vertical calendar list	true

Understanding calendar component

To give accurate height of a calendar in a calendar list, we need to understand what makes a calendar in a calendar list. The image below has three sections;

• Red Section: This is the monthTitle section, this is where MonthNameComponent is rendered when showMonthName=true. estimatedCalendarSize.monthTitleSize is equal to the height of this component if showMonthName=true otherwise 0
• Blue Section: This is the weekDayNames section, this is where WeekDayNameComponent is rendered when showDayNames=true && showDayNamesOnTop=false. estimatedCalendarSize.weekDayNamesSize is equal to the height of this component if showDayNames=true && showDayNamesOnTop=false otherwise 0
• Green Section: This is entire calendar height, and it is made of the height of monthTitle weekDayNames and weeks. Since a calendar may have 5 or 6 weeks, we use the height of a calendar with 5 weeks for estimatedCalendarSize.fiveWeekCalendarSize