feat: Add CalendarCarousel component #9079

devongovett · 2025-10-22T00:32:18Z

(Opening for team discussion)

This started as an idea for a docs example: a calendar where you could swipe to navigate between months like the native iOS calendar. It is possible to build today with our existing API: https://stackblitz.com/edit/rac-swipeable-calendar?file=src%2FCalendar.tsx. But then I thought: why not just add this as a built-in component?

The new CalendarCarousel component (name TBD) uses CSS scroll snapping to allow native swipe gestures between months. The current month is centered in the viewport, with one extra month on either side, along with a placeholder div that takes up a large number of pages.

As you swipe, the months update and the placeholder shrinks giving the illusion of infinite pages. When you stop scrolling, the scroll position is re-centered and the placeholders become equal size again. This avoids changing the scroll positioning while the user is scrolling, which causes jumpiness. The placeholders are large to make it unlikely that the user will reach the end without stopping.

Questions

Do we want to add this component?
What should we call it?
Should it somehow respect pageBehavior?
Are the built-in inline styles too specific? We haven't had a component like this before where some styles are set by us.
Inline comments

devongovett · 2025-10-22T00:34:02Z

packages/dev/s2-docs/pages/react-aria/Calendar.mdx

-      {date => <CalendarCell date={date} />}
-    </CalendarGridBody>
-  </CalendarGrid>
+  <CalendarCarousel> (optional)


Should we show that this component is optional? I guess we don't do this anywhere else, but I'm not sure we have other optional components that accept children?

I think this could make sense for Virtualizer in some examples, e.g. Virtualized Select, to illustrate where the Virtualizer goes.

devongovett · 2025-10-22T00:35:06Z

packages/react-aria-components/src/Calendar.tsx

+        {/* contain: 'inline-size' makes these extra pages not affect the width of the parent */}
+        <div inert style={{width: '100%', flexShrink: 0, contain: 'inline-size', scrollSnapAlign: 'start', scrollSnapStop: 'always'}}>
+          <CalendarGridContext.Provider value={{offset: {months: -state.visibleDuration.months!}}}>
+            {props.children}


Note that this duplicates the children 3 times, and uses context to offset the months

devongovett · 2025-10-22T00:35:25Z

packages/react-aria-components/src/Calendar.tsx

 * can be keyboard navigated and selected by the user.
 */
 export const CalendarGrid = /*#__PURE__*/ (forwardRef as forwardRefType)(function CalendarGrid(props: CalendarGridProps, ref: ForwardedRef<HTMLTableElement>) {
+  // Merge offset from context with props.


Weird? Otherwise I have to add a render prop function to the CalendarCarousel, pass in the offset, and make the user apply it manually.

We have precedence of doing something similar to this for layoutOptions, so I think fine 👍

rspbot · 2025-10-22T00:40:18Z

Build successful! 🎉

rspbot · 2025-10-22T01:03:00Z

Build successful! 🎉

rspbot · 2025-10-22T01:03:02Z

## API Changes

react-aria-components

/react-aria-components:CalendarState

 CalendarState {
   focusNextDay: () => void
   focusNextPage: () => void
   focusNextRow: () => void
   focusNextSection: (boolean) => void
   focusPreviousDay: () => void
   focusPreviousPage: () => void
   focusPreviousRow: () => void
   focusPreviousSection: (boolean) => void
   focusSectionEnd: () => void
   focusSectionStart: () => void
   focusedDate: CalendarDate
   getDatesInWeek: (number, CalendarDate) => Array<CalendarDate | null>
   isCellDisabled: (CalendarDate) => boolean
   isCellFocused: (CalendarDate) => boolean
   isCellUnavailable: (CalendarDate) => boolean
   isDisabled: boolean
   isFocused: boolean
   isInvalid: (CalendarDate) => boolean
   isNextVisibleRangeInvalid: () => boolean
   isPreviousVisibleRangeInvalid: () => boolean
   isReadOnly: boolean
   isSelected: (CalendarDate) => boolean
   isValueInvalid: boolean
   maxValue?: DateValue | null
   minValue?: DateValue | null
   selectDate: (CalendarDate) => void
   selectFocusedDate: () => void
   setFocused: (boolean) => void
-  setFocusedDate: (CalendarDate) => void
+  setFocusedDate: (CalendarDate, 'start' | 'center' | 'end') => void
   setValue: (CalendarDate | null) => void
   timeZone: string
   value: CalendarDate | null
+  visibleDuration: DateDuration
   visibleRange: RangeValue<CalendarDate>
 }

/react-aria-components:RangeCalendarState

 RangeCalendarState <T extends DateValue = DateValue> {
   anchorDate: CalendarDate | null
   focusNextDay: () => void
   focusNextPage: () => void
   focusNextRow: () => void
   focusNextSection: (boolean) => void
   focusPreviousDay: () => void
   focusPreviousPage: () => void
   focusPreviousRow: () => void
   focusPreviousSection: (boolean) => void
   focusSectionEnd: () => void
   focusSectionStart: () => void
   focusedDate: CalendarDate
   getDatesInWeek: (number, CalendarDate) => Array<CalendarDate | null>
   highlightDate: (CalendarDate) => void
   highlightedRange: RangeValue<CalendarDate> | null
   isCellDisabled: (CalendarDate) => boolean
   isCellFocused: (CalendarDate) => boolean
   isCellUnavailable: (CalendarDate) => boolean
   isDisabled: boolean
   isDragging: boolean
   isFocused: boolean
   isInvalid: (CalendarDate) => boolean
   isNextVisibleRangeInvalid: () => boolean
   isPreviousVisibleRangeInvalid: () => boolean
   isReadOnly: boolean
   isSelected: (CalendarDate) => boolean
   isValueInvalid: boolean
   maxValue?: DateValue | null
   minValue?: DateValue | null
   selectDate: (CalendarDate) => void
   selectFocusedDate: () => void
   setAnchorDate: (CalendarDate | null) => void
   setDragging: (boolean) => void
   setFocused: (boolean) => void
-  setFocusedDate: (CalendarDate) => void
+  setFocusedDate: (CalendarDate, 'start' | 'center' | 'end') => void
   setValue: (RangeValue<DateValue> | null) => void
   timeZone: string
   value: RangeValue<DateValue> | null
+  visibleDuration: DateDuration
   visibleRange: RangeValue<CalendarDate>
 }

/react-aria-components:CalendarCarousel

+CalendarCarousel {
+  children: ReactNode
+  className?: string = 'react-aria-CalendarCarousel'
+  style?: CSSProperties
+}

/react-aria-components:CalendarCarouselProps

+CalendarCarouselProps {
+  children: ReactNode
+  className?: string = 'react-aria-CalendarCarousel'
+  style?: CSSProperties
+}

@react-stately/calendar

/@react-stately/calendar:CalendarState

 CalendarState {
   focusNextDay: () => void
   focusNextPage: () => void
   focusNextRow: () => void
   focusNextSection: (boolean) => void
   focusPreviousDay: () => void
   focusPreviousPage: () => void
   focusPreviousRow: () => void
   focusPreviousSection: (boolean) => void
   focusSectionEnd: () => void
   focusSectionStart: () => void
   focusedDate: CalendarDate
   getDatesInWeek: (number, CalendarDate) => Array<CalendarDate | null>
   isCellDisabled: (CalendarDate) => boolean
   isCellFocused: (CalendarDate) => boolean
   isCellUnavailable: (CalendarDate) => boolean
   isDisabled: boolean
   isFocused: boolean
   isInvalid: (CalendarDate) => boolean
   isNextVisibleRangeInvalid: () => boolean
   isPreviousVisibleRangeInvalid: () => boolean
   isReadOnly: boolean
   isSelected: (CalendarDate) => boolean
   isValueInvalid: boolean
   maxValue?: DateValue | null
   minValue?: DateValue | null
   selectDate: (CalendarDate) => void
   selectFocusedDate: () => void
   setFocused: (boolean) => void
-  setFocusedDate: (CalendarDate) => void
+  setFocusedDate: (CalendarDate, 'start' | 'center' | 'end') => void
   setValue: (CalendarDate | null) => void
   timeZone: string
   value: CalendarDate | null
+  visibleDuration: DateDuration
   visibleRange: RangeValue<CalendarDate>
 }

/@react-stately/calendar:RangeCalendarState

 RangeCalendarState <T extends DateValue = DateValue> {
   anchorDate: CalendarDate | null
   focusNextDay: () => void
   focusNextPage: () => void
   focusNextRow: () => void
   focusNextSection: (boolean) => void
   focusPreviousDay: () => void
   focusPreviousPage: () => void
   focusPreviousRow: () => void
   focusPreviousSection: (boolean) => void
   focusSectionEnd: () => void
   focusSectionStart: () => void
   focusedDate: CalendarDate
   getDatesInWeek: (number, CalendarDate) => Array<CalendarDate | null>
   highlightDate: (CalendarDate) => void
   highlightedRange: RangeValue<CalendarDate> | null
   isCellDisabled: (CalendarDate) => boolean
   isCellFocused: (CalendarDate) => boolean
   isCellUnavailable: (CalendarDate) => boolean
   isDisabled: boolean
   isDragging: boolean
   isFocused: boolean
   isInvalid: (CalendarDate) => boolean
   isNextVisibleRangeInvalid: () => boolean
   isPreviousVisibleRangeInvalid: () => boolean
   isReadOnly: boolean
   isSelected: (CalendarDate) => boolean
   isValueInvalid: boolean
   maxValue?: DateValue | null
   minValue?: DateValue | null
   selectDate: (CalendarDate) => void
   selectFocusedDate: () => void
   setAnchorDate: (CalendarDate | null) => void
   setDragging: (boolean) => void
   setFocused: (boolean) => void
-  setFocusedDate: (CalendarDate) => void
+  setFocusedDate: (CalendarDate, 'start' | 'center' | 'end') => void
   setValue: (RangeValue<DateValue> | null) => void
   timeZone: string
   value: RangeValue<DateValue> | null
+  visibleDuration: DateDuration
   visibleRange: RangeValue<CalendarDate>
 }

nwidynski · 2025-10-22T15:40:16Z

packages/react-aria-components/src/Calendar.tsx

+    clearTimeout(timeout.current);
+    timeout.current = setTimeout(() => {
+      let index = el.scrollLeft / el.offsetWidth;
+      if (Math.abs(Math.round(index) - index) < 0.01) {
+        dispatch({type: 'SCROLL_END', visibleMonths: state.visibleDuration.months!});
+      }
+    }, 500);
+  };


We could probably work the same performance optimization here as in useScrollView, aka. rescheduling only when getting close to the end of the interval?

feat: Add CalendarCarousel component

de74519

devongovett commented Oct 22, 2025

View reviewed changes

prevent text selection

f745d7c

nwidynski reviewed Oct 22, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

feat: Add CalendarCarousel component #9079

feat: Add CalendarCarousel component #9079

devongovett commented Oct 22, 2025 •

edited

Loading

Uh oh!

devongovett Oct 22, 2025

Uh oh!

nwidynski Oct 22, 2025

Uh oh!

devongovett Oct 22, 2025

Uh oh!

devongovett Oct 22, 2025

Uh oh!

nwidynski Oct 22, 2025 •

edited

Loading

Uh oh!

rspbot commented Oct 22, 2025

Uh oh!

rspbot commented Oct 22, 2025

Uh oh!

rspbot commented Oct 22, 2025

Uh oh!

nwidynski Oct 22, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

feat: Add CalendarCarousel component #9079

Are you sure you want to change the base?

feat: Add CalendarCarousel component #9079

Conversation

devongovett commented Oct 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Questions

Uh oh!

devongovett Oct 22, 2025

Choose a reason for hiding this comment

Uh oh!

nwidynski Oct 22, 2025

Choose a reason for hiding this comment

Uh oh!

devongovett Oct 22, 2025

Choose a reason for hiding this comment

Uh oh!

devongovett Oct 22, 2025

Choose a reason for hiding this comment

Uh oh!

nwidynski Oct 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rspbot commented Oct 22, 2025

Uh oh!

rspbot commented Oct 22, 2025

Uh oh!

rspbot commented Oct 22, 2025

react-aria-components

/react-aria-components:CalendarState

/react-aria-components:RangeCalendarState

/react-aria-components:CalendarCarousel

/react-aria-components:CalendarCarouselProps

@react-stately/calendar

/@react-stately/calendar:CalendarState

/@react-stately/calendar:RangeCalendarState

Uh oh!

nwidynski Oct 22, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

devongovett commented Oct 22, 2025 •

edited

Loading

nwidynski Oct 22, 2025 •

edited

Loading