Skip to content

feat: support selectionAlignment in Calendar #8752

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

feat: support selectionAlignment in Calendar #8752

wants to merge 3 commits into from
+178 −9

Conversation

yihuiliao
Copy link
Member

@yihuiliao yihuiliao commented Aug 21, 2025 •
edited
Loading

Closes #4721, #8149

✅ Pull Request Checklist:

  • Included link to corresponding React Spectrum GitHub Issue.
  • Added/updated unit tests and storybook for this change (for new code or code which already has tests).
  • Filled out test instructions.
  • Updated documentation (if it already exists for this component).
  • Looked at the Accessibility Practices for this feature - Aria Practices

📝 Test Instructions:

Test out both RAC and V3 Calendar/RangeCalender when there are multiple months displayed. For some reason, when you change the value of the selectionAlignment, it doesn't update in the storybook automatically so you have to remount it...

🧢 Your Project:

@yihuiliao yihuiliao changed the title feat: support selectionAlignment in Calendar wip: support selectionAlignment in Calendar Aug 21, 2025
@rspbot
Copy link

rspbot commented Aug 21, 2025

Build successful! 🎉

@yihuiliao yihuiliao changed the title wip: support selectionAlignment in Calendar feat: support selectionAlignment in Calendar Aug 27, 2025
@yihuiliao yihuiliao marked this pull request as ready for review August 27, 2025 23:21
@rspbot
Copy link

rspbot commented Aug 27, 2025

Build successful! 🎉

@rspbot
Copy link

rspbot commented Aug 27, 2025

## API Changes

react-aria-components

/react-aria-components:Calendar

 Calendar <T extends DateValue> {
   aria-describedby?: string
   aria-details?: string
   aria-label?: string
   aria-labelledby?: string
   autoFocus?: boolean = false
   children?: ChildrenOrFunction<CalendarRenderProps>
   className?: ClassNameOrFunction<CalendarRenderProps>
   createCalendar?: (CalendarIdentifier) => Calendar
   defaultFocusedValue?: DateValue | null
   defaultValue?: DateValue | null
   firstDayOfWeek?: 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'
   focusedValue?: DateValue | null
   id?: string
   isDateUnavailable?: (DateValue) => boolean
   isDisabled?: boolean = false
   isInvalid?: boolean
   isReadOnly?: boolean = false
   maxValue?: DateValue | null
   minValue?: DateValue | null
   onChange?: (MappedDateValue<DateValue>) => void
   onFocusChange?: (CalendarDate) => void
   pageBehavior?: PageBehavior = visible
+  selectionAlignment?: 'start' | 'center' | 'end'
   slot?: string | null
   style?: StyleOrFunction<CalendarRenderProps>
   value?: DateValue | null
   visibleDuration?: DateDuration = {months: 1}

/react-aria-components:RangeCalendar

 RangeCalendar <T extends DateValue> {
   allowsNonContiguousRanges?: boolean
   aria-describedby?: string
   aria-details?: string
   aria-label?: string
   aria-labelledby?: string
   autoFocus?: boolean = false
   children?: ChildrenOrFunction<RangeCalendarRenderProps>
   className?: ClassNameOrFunction<RangeCalendarRenderProps>
   createCalendar?: (CalendarIdentifier) => Calendar
   defaultFocusedValue?: DateValue | null
   defaultValue?: RangeValue<DateValue> | null
   firstDayOfWeek?: 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'
   focusedValue?: DateValue | null
   id?: string
   isDateUnavailable?: (DateValue) => boolean
   isDisabled?: boolean = false
   isInvalid?: boolean
   isReadOnly?: boolean = false
   maxValue?: DateValue | null
   minValue?: DateValue | null
   onChange?: (RangeValue<MappedDateValue<DateValue>>) => void
   onFocusChange?: (CalendarDate) => void
   pageBehavior?: PageBehavior = visible
+  selectionAlignment?: 'start' | 'center' | 'end'
   slot?: string | null
   style?: StyleOrFunction<RangeCalendarRenderProps>
   value?: RangeValue<DateValue> | null
   visibleDuration?: DateDuration = {months: 1}

/react-aria-components:CalendarProps

 CalendarProps <T extends DateValue> {
   aria-describedby?: string
   aria-details?: string
   aria-label?: string
   aria-labelledby?: string
   autoFocus?: boolean = false
   children?: ChildrenOrFunction<CalendarRenderProps>
   className?: ClassNameOrFunction<CalendarRenderProps>
   createCalendar?: (CalendarIdentifier) => Calendar
   defaultFocusedValue?: DateValue | null
   defaultValue?: DateValue | null
   firstDayOfWeek?: 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'
   focusedValue?: DateValue | null
   id?: string
   isDateUnavailable?: (DateValue) => boolean
   isDisabled?: boolean = false
   isInvalid?: boolean
   isReadOnly?: boolean = false
   maxValue?: DateValue | null
   minValue?: DateValue | null
   onChange?: (MappedDateValue<DateValue>) => void
   onFocusChange?: (CalendarDate) => void
   pageBehavior?: PageBehavior = visible
+  selectionAlignment?: 'start' | 'center' | 'end'
   slot?: string | null
   style?: StyleOrFunction<CalendarRenderProps>
   value?: DateValue | null
   visibleDuration?: DateDuration = {months: 1}

/react-aria-components:RangeCalendarProps

 RangeCalendarProps <T extends DateValue> {
   allowsNonContiguousRanges?: boolean
   aria-describedby?: string
   aria-details?: string
   aria-label?: string
   aria-labelledby?: string
   autoFocus?: boolean = false
   children?: ChildrenOrFunction<RangeCalendarRenderProps>
   className?: ClassNameOrFunction<RangeCalendarRenderProps>
   createCalendar?: (CalendarIdentifier) => Calendar
   defaultFocusedValue?: DateValue | null
   defaultValue?: RangeValue<DateValue> | null
   firstDayOfWeek?: 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'
   focusedValue?: DateValue | null
   id?: string
   isDateUnavailable?: (DateValue) => boolean
   isDisabled?: boolean = false
   isInvalid?: boolean
   isReadOnly?: boolean = false
   maxValue?: DateValue | null
   minValue?: DateValue | null
   onChange?: (RangeValue<MappedDateValue<DateValue>>) => void
   onFocusChange?: (CalendarDate) => void
   pageBehavior?: PageBehavior = visible
+  selectionAlignment?: 'start' | 'center' | 'end'
   slot?: string | null
   style?: StyleOrFunction<RangeCalendarRenderProps>
   value?: RangeValue<DateValue> | null
   visibleDuration?: DateDuration = {months: 1}

@react-aria/calendar

/@react-aria/calendar:AriaCalendarProps

 AriaCalendarProps <T extends DateValue> {
   aria-describedby?: string
   aria-details?: string
   aria-label?: string
   aria-labelledby?: string
   autoFocus?: boolean = false
   defaultFocusedValue?: DateValue | null
   defaultValue?: DateValue | null
   errorMessage?: ReactNode
   firstDayOfWeek?: 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'
   focusedValue?: DateValue | null
   id?: string
   isDateUnavailable?: (DateValue) => boolean
   isDisabled?: boolean = false
   isInvalid?: boolean
   isReadOnly?: boolean = false
   maxValue?: DateValue | null
   minValue?: DateValue | null
   onChange?: (MappedDateValue<DateValue>) => void
   onFocusChange?: (CalendarDate) => void
   pageBehavior?: PageBehavior = visible
+  selectionAlignment?: 'start' | 'center' | 'end'
   value?: DateValue | null
 }

/@react-aria/calendar:AriaRangeCalendarProps

 AriaRangeCalendarProps <T extends DateValue> {
   allowsNonContiguousRanges?: boolean
   aria-describedby?: string
   aria-details?: string
   aria-label?: string
   aria-labelledby?: string
   autoFocus?: boolean = false
   defaultFocusedValue?: DateValue | null
   defaultValue?: RangeValue<DateValue> | null
   errorMessage?: ReactNode
   firstDayOfWeek?: 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'
   focusedValue?: DateValue | null
   id?: string
   isDateUnavailable?: (DateValue) => boolean
   isDisabled?: boolean = false
   isInvalid?: boolean
   isReadOnly?: boolean = false
   maxValue?: DateValue | null
   minValue?: DateValue | null
   onChange?: (RangeValue<MappedDateValue<DateValue>>) => void
   onFocusChange?: (CalendarDate) => void
   pageBehavior?: PageBehavior = visible
+  selectionAlignment?: 'start' | 'center' | 'end'
   value?: RangeValue<DateValue> | null
 }

/@react-aria/calendar:CalendarProps

 CalendarProps <T extends DateValue> {
   autoFocus?: boolean = false
   defaultFocusedValue?: DateValue | null
   defaultValue?: DateValue | null
   errorMessage?: ReactNode
   firstDayOfWeek?: 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'
   focusedValue?: DateValue | null
   isDateUnavailable?: (DateValue) => boolean
   isDisabled?: boolean = false
   isInvalid?: boolean
   isReadOnly?: boolean = false
   maxValue?: DateValue | null
   minValue?: DateValue | null
   onChange?: (MappedDateValue<DateValue>) => void
   onFocusChange?: (CalendarDate) => void
   pageBehavior?: PageBehavior = visible
+  selectionAlignment?: 'start' | 'center' | 'end'
   value?: DateValue | null
 }

/@react-aria/calendar:RangeCalendarProps

 RangeCalendarProps <T extends DateValue> {
   allowsNonContiguousRanges?: boolean
   autoFocus?: boolean = false
   defaultFocusedValue?: DateValue | null
   defaultValue?: RangeValue<DateValue> | null
   errorMessage?: ReactNode
   firstDayOfWeek?: 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'
   focusedValue?: DateValue | null
   isDateUnavailable?: (DateValue) => boolean
   isDisabled?: boolean = false
   isInvalid?: boolean
   isReadOnly?: boolean = false
   maxValue?: DateValue | null
   minValue?: DateValue | null
   onChange?: (RangeValue<MappedDateValue<DateValue>>) => void
   onFocusChange?: (CalendarDate) => void
   pageBehavior?: PageBehavior = visible
+  selectionAlignment?: 'start' | 'center' | 'end'
   value?: RangeValue<DateValue> | null
 }

@react-spectrum/calendar

/@react-spectrum/calendar:Calendar

 Calendar <T extends DateValue> {
   UNSAFE_className?: string
   UNSAFE_style?: CSSProperties
   alignSelf?: Responsive<'auto' | 'normal' | 'start' | 'end' | 'center' | 'flex-start' | 'flex-end' | 'self-start' | 'self-end' | 'stretch'>
   aria-describedby?: string
   aria-details?: string
   aria-label?: string
   aria-labelledby?: string
   autoFocus?: boolean = false
   bottom?: Responsive<DimensionValue>
   createCalendar?: (CalendarIdentifier) => Calendar
   defaultFocusedValue?: DateValue | null
   defaultValue?: DateValue | null
   end?: Responsive<DimensionValue>
   errorMessage?: ReactNode
   firstDayOfWeek?: 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'
   flex?: Responsive<string | number | boolean>
   flexBasis?: Responsive<number | string>
   flexGrow?: Responsive<number>
   flexShrink?: Responsive<number>
   focusedValue?: DateValue | null
   gridArea?: Responsive<string>
   gridColumn?: Responsive<string>
   gridColumnEnd?: Responsive<string>
   gridColumnStart?: Responsive<string>
   gridRow?: Responsive<string>
   gridRowEnd?: Responsive<string>
   gridRowStart?: Responsive<string>
   height?: Responsive<DimensionValue>
   id?: string
   isDateUnavailable?: (DateValue) => boolean
   isDisabled?: boolean = false
   isHidden?: Responsive<boolean>
   isInvalid?: boolean
   isReadOnly?: boolean = false
   justifySelf?: Responsive<'auto' | 'normal' | 'start' | 'end' | 'flex-start' | 'flex-end' | 'self-start' | 'self-end' | 'center' | 'left' | 'right' | 'stretch'>
   left?: Responsive<DimensionValue>
   margin?: Responsive<DimensionValue>
   marginBottom?: Responsive<DimensionValue>
   marginEnd?: Responsive<DimensionValue>
   marginStart?: Responsive<DimensionValue>
   marginTop?: Responsive<DimensionValue>
   marginX?: Responsive<DimensionValue>
   marginY?: Responsive<DimensionValue>
   maxHeight?: Responsive<DimensionValue>
   maxValue?: DateValue | null
   maxWidth?: Responsive<DimensionValue>
   minHeight?: Responsive<DimensionValue>
   minValue?: DateValue | null
   minWidth?: Responsive<DimensionValue>
   onChange?: (MappedDateValue<DateValue>) => void
   onFocusChange?: (CalendarDate) => void
   order?: Responsive<number>
   pageBehavior?: PageBehavior = visible
   position?: Responsive<'static' | 'relative' | 'absolute' | 'fixed' | 'sticky'>
   right?: Responsive<DimensionValue>
+  selectionAlignment?: 'start' | 'center' | 'end'
   start?: Responsive<DimensionValue>
   top?: Responsive<DimensionValue>
   value?: DateValue | null
   visibleMonths?: number = 1
   zIndex?: Responsive<number>
 }

/@react-spectrum/calendar:RangeCalendar

 RangeCalendar <T extends DateValue> {
   UNSAFE_className?: string
   UNSAFE_style?: CSSProperties
   alignSelf?: Responsive<'auto' | 'normal' | 'start' | 'end' | 'center' | 'flex-start' | 'flex-end' | 'self-start' | 'self-end' | 'stretch'>
   allowsNonContiguousRanges?: boolean
   aria-describedby?: string
   aria-details?: string
   aria-label?: string
   aria-labelledby?: string
   autoFocus?: boolean = false
   bottom?: Responsive<DimensionValue>
   createCalendar?: (CalendarIdentifier) => Calendar
   defaultFocusedValue?: DateValue | null
   defaultValue?: RangeValue<DateValue> | null
   end?: Responsive<DimensionValue>
   errorMessage?: ReactNode
   firstDayOfWeek?: 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'
   flex?: Responsive<string | number | boolean>
   flexBasis?: Responsive<number | string>
   flexGrow?: Responsive<number>
   flexShrink?: Responsive<number>
   focusedValue?: DateValue | null
   gridArea?: Responsive<string>
   gridColumn?: Responsive<string>
   gridColumnEnd?: Responsive<string>
   gridColumnStart?: Responsive<string>
   gridRow?: Responsive<string>
   gridRowEnd?: Responsive<string>
   gridRowStart?: Responsive<string>
   height?: Responsive<DimensionValue>
   id?: string
   isDateUnavailable?: (DateValue) => boolean
   isDisabled?: boolean = false
   isHidden?: Responsive<boolean>
   isInvalid?: boolean
   isReadOnly?: boolean = false
   justifySelf?: Responsive<'auto' | 'normal' | 'start' | 'end' | 'flex-start' | 'flex-end' | 'self-start' | 'self-end' | 'center' | 'left' | 'right' | 'stretch'>
   left?: Responsive<DimensionValue>
   margin?: Responsive<DimensionValue>
   marginBottom?: Responsive<DimensionValue>
   marginEnd?: Responsive<DimensionValue>
   marginStart?: Responsive<DimensionValue>
   marginTop?: Responsive<DimensionValue>
   marginX?: Responsive<DimensionValue>
   marginY?: Responsive<DimensionValue>
   maxHeight?: Responsive<DimensionValue>
   maxValue?: DateValue | null
   maxWidth?: Responsive<DimensionValue>
   minHeight?: Responsive<DimensionValue>
   minValue?: DateValue | null
   minWidth?: Responsive<DimensionValue>
   onChange?: (RangeValue<MappedDateValue<DateValue>>) => void
   onFocusChange?: (CalendarDate) => void
   order?: Responsive<number>
   pageBehavior?: PageBehavior = visible
   position?: Responsive<'static' | 'relative' | 'absolute' | 'fixed' | 'sticky'>
   right?: Responsive<DimensionValue>
+  selectionAlignment?: 'start' | 'center' | 'end'
   start?: Responsive<DimensionValue>
   top?: Responsive<DimensionValue>
   value?: RangeValue<DateValue> | null
   visibleMonths?: number = 1
   zIndex?: Responsive<number>
 }

/@react-spectrum/calendar:SpectrumCalendarProps

 SpectrumCalendarProps <T extends DateValue> {
   UNSAFE_className?: string
   UNSAFE_style?: CSSProperties
   alignSelf?: Responsive<'auto' | 'normal' | 'start' | 'end' | 'center' | 'flex-start' | 'flex-end' | 'self-start' | 'self-end' | 'stretch'>
   aria-describedby?: string
   aria-details?: string
   aria-label?: string
   aria-labelledby?: string
   autoFocus?: boolean = false
   bottom?: Responsive<DimensionValue>
   createCalendar?: (CalendarIdentifier) => Calendar
   defaultFocusedValue?: DateValue | null
   defaultValue?: DateValue | null
   end?: Responsive<DimensionValue>
   errorMessage?: ReactNode
   firstDayOfWeek?: 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'
   flex?: Responsive<string | number | boolean>
   flexBasis?: Responsive<number | string>
   flexGrow?: Responsive<number>
   flexShrink?: Responsive<number>
   focusedValue?: DateValue | null
   gridArea?: Responsive<string>
   gridColumn?: Responsive<string>
   gridColumnEnd?: Responsive<string>
   gridColumnStart?: Responsive<string>
   gridRow?: Responsive<string>
   gridRowEnd?: Responsive<string>
   gridRowStart?: Responsive<string>
   height?: Responsive<DimensionValue>
   id?: string
   isDateUnavailable?: (DateValue) => boolean
   isDisabled?: boolean = false
   isHidden?: Responsive<boolean>
   isInvalid?: boolean
   isReadOnly?: boolean = false
   justifySelf?: Responsive<'auto' | 'normal' | 'start' | 'end' | 'flex-start' | 'flex-end' | 'self-start' | 'self-end' | 'center' | 'left' | 'right' | 'stretch'>
   left?: Responsive<DimensionValue>
   margin?: Responsive<DimensionValue>
   marginBottom?: Responsive<DimensionValue>
   marginEnd?: Responsive<DimensionValue>
   marginStart?: Responsive<DimensionValue>
   marginTop?: Responsive<DimensionValue>
   marginX?: Responsive<DimensionValue>
   marginY?: Responsive<DimensionValue>
   maxHeight?: Responsive<DimensionValue>
   maxValue?: DateValue | null
   maxWidth?: Responsive<DimensionValue>
   minHeight?: Responsive<DimensionValue>
   minValue?: DateValue | null
   minWidth?: Responsive<DimensionValue>
   onChange?: (MappedDateValue<DateValue>) => void
   onFocusChange?: (CalendarDate) => void
   order?: Responsive<number>
   pageBehavior?: PageBehavior = visible
   position?: Responsive<'static' | 'relative' | 'absolute' | 'fixed' | 'sticky'>
   right?: Responsive<DimensionValue>
+  selectionAlignment?: 'start' | 'center' | 'end'
   start?: Responsive<DimensionValue>
   top?: Responsive<DimensionValue>
   value?: DateValue | null
   visibleMonths?: number = 1
   zIndex?: Responsive<number>
 }

/@react-spectrum/calendar:SpectrumRangeCalendarProps

 SpectrumRangeCalendarProps <T extends DateValue> {
   UNSAFE_className?: string
   UNSAFE_style?: CSSProperties
   alignSelf?: Responsive<'auto' | 'normal' | 'start' | 'end' | 'center' | 'flex-start' | 'flex-end' | 'self-start' | 'self-end' | 'stretch'>
   allowsNonContiguousRanges?: boolean
   aria-describedby?: string
   aria-details?: string
   aria-label?: string
   aria-labelledby?: string
   autoFocus?: boolean = false
   bottom?: Responsive<DimensionValue>
   createCalendar?: (CalendarIdentifier) => Calendar
   defaultFocusedValue?: DateValue | null
   defaultValue?: RangeValue<DateValue> | null
   end?: Responsive<DimensionValue>
   errorMessage?: ReactNode
   firstDayOfWeek?: 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'
   flex?: Responsive<string | number | boolean>
   flexBasis?: Responsive<number | string>
   flexGrow?: Responsive<number>
   flexShrink?: Responsive<number>
   focusedValue?: DateValue | null
   gridArea?: Responsive<string>
   gridColumn?: Responsive<string>
   gridColumnEnd?: Responsive<string>
   gridColumnStart?: Responsive<string>
   gridRow?: Responsive<string>
   gridRowEnd?: Responsive<string>
   gridRowStart?: Responsive<string>
   height?: Responsive<DimensionValue>
   id?: string
   isDateUnavailable?: (DateValue) => boolean
   isDisabled?: boolean = false
   isHidden?: Responsive<boolean>
   isInvalid?: boolean
   isReadOnly?: boolean = false
   justifySelf?: Responsive<'auto' | 'normal' | 'start' | 'end' | 'flex-start' | 'flex-end' | 'self-start' | 'self-end' | 'center' | 'left' | 'right' | 'stretch'>
   left?: Responsive<DimensionValue>
   margin?: Responsive<DimensionValue>
   marginBottom?: Responsive<DimensionValue>
   marginEnd?: Responsive<DimensionValue>
   marginStart?: Responsive<DimensionValue>
   marginTop?: Responsive<DimensionValue>
   marginX?: Responsive<DimensionValue>
   marginY?: Responsive<DimensionValue>
   maxHeight?: Responsive<DimensionValue>
   maxValue?: DateValue | null
   maxWidth?: Responsive<DimensionValue>
   minHeight?: Responsive<DimensionValue>
   minValue?: DateValue | null
   minWidth?: Responsive<DimensionValue>
   onChange?: (RangeValue<MappedDateValue<DateValue>>) => void
   onFocusChange?: (CalendarDate) => void
   order?: Responsive<number>
   pageBehavior?: PageBehavior = visible
   position?: Responsive<'static' | 'relative' | 'absolute' | 'fixed' | 'sticky'>
   right?: Responsive<DimensionValue>
+  selectionAlignment?: 'start' | 'center' | 'end'
   start?: Responsive<DimensionValue>
   top?: Responsive<DimensionValue>
   value?: RangeValue<DateValue> | null
   visibleMonths?: number = 1
   zIndex?: Responsive<number>
 }

@react-spectrum/s2

/@react-spectrum/s2:Calendar

 Calendar <T extends DateValue> {
   UNSAFE_className?: UnsafeClassName
   UNSAFE_style?: CSSProperties
   aria-describedby?: string
   aria-details?: string
   aria-label?: string
   aria-labelledby?: string
   autoFocus?: boolean = false
   children?: ChildrenOrFunction<CalendarRenderProps>
   createCalendar?: (CalendarIdentifier) => Calendar
   defaultFocusedValue?: DateValue | null
   defaultValue?: DateValue | null
   errorMessage?: ReactNode
   firstDayOfWeek?: 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'
   focusedValue?: DateValue | null
   id?: string
   isDateUnavailable?: (DateValue) => boolean
   isDisabled?: boolean = false
   isInvalid?: boolean
   isReadOnly?: boolean = false
   maxValue?: DateValue | null
   minValue?: DateValue | null
   onChange?: (MappedDateValue<DateValue>) => void
   onFocusChange?: (CalendarDate) => void
   pageBehavior?: PageBehavior = visible
+  selectionAlignment?: 'start' | 'center' | 'end'
   slot?: string | null
   styles?: StylesProp
   value?: DateValue | null
   visibleMonths?: number = 1

/@react-spectrum/s2:RangeCalendar

 RangeCalendar <T extends DateValue> {
   UNSAFE_className?: UnsafeClassName
   UNSAFE_style?: CSSProperties
   allowsNonContiguousRanges?: boolean
   aria-describedby?: string
   aria-details?: string
   aria-label?: string
   aria-labelledby?: string
   autoFocus?: boolean = false
   children?: ChildrenOrFunction<RangeCalendarRenderProps>
   createCalendar?: (CalendarIdentifier) => Calendar
   defaultFocusedValue?: DateValue | null
   defaultValue?: RangeValue<DateValue> | null
   errorMessage?: ReactNode
   firstDayOfWeek?: 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'
   focusedValue?: DateValue | null
   id?: string
   isDateUnavailable?: (DateValue) => boolean
   isDisabled?: boolean = false
   isInvalid?: boolean
   isReadOnly?: boolean = false
   maxValue?: DateValue | null
   minValue?: DateValue | null
   onChange?: (RangeValue<MappedDateValue<DateValue>>) => void
   onFocusChange?: (CalendarDate) => void
   pageBehavior?: PageBehavior = visible
+  selectionAlignment?: 'start' | 'center' | 'end'
   slot?: string | null
   styles?: StylesProp
   value?: RangeValue<DateValue> | null
   visibleMonths?: number = 1

/@react-spectrum/s2:CalendarProps

 CalendarProps <T extends DateValue> {
   UNSAFE_className?: UnsafeClassName
   UNSAFE_style?: CSSProperties
   aria-describedby?: string
   aria-details?: string
   aria-label?: string
   aria-labelledby?: string
   autoFocus?: boolean = false
   children?: ChildrenOrFunction<CalendarRenderProps>
   createCalendar?: (CalendarIdentifier) => Calendar
   defaultFocusedValue?: DateValue | null
   defaultValue?: DateValue | null
   errorMessage?: ReactNode
   firstDayOfWeek?: 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'
   focusedValue?: DateValue | null
   id?: string
   isDateUnavailable?: (DateValue) => boolean
   isDisabled?: boolean = false
   isInvalid?: boolean
   isReadOnly?: boolean = false
   maxValue?: DateValue | null
   minValue?: DateValue | null
   onChange?: (MappedDateValue<DateValue>) => void
   onFocusChange?: (CalendarDate) => void
   pageBehavior?: PageBehavior = visible
+  selectionAlignment?: 'start' | 'center' | 'end'
   slot?: string | null
   styles?: StylesProp
   value?: DateValue | null
   visibleMonths?: number = 1

/@react-spectrum/s2:RangeCalendarProps

 RangeCalendarProps <T extends DateValue> {
   UNSAFE_className?: UnsafeClassName
   UNSAFE_style?: CSSProperties
   allowsNonContiguousRanges?: boolean
   aria-describedby?: string
   aria-details?: string
   aria-label?: string
   aria-labelledby?: string
   autoFocus?: boolean = false
   children?: ChildrenOrFunction<RangeCalendarRenderProps>
   createCalendar?: (CalendarIdentifier) => Calendar
   defaultFocusedValue?: DateValue | null
   defaultValue?: RangeValue<DateValue> | null
   errorMessage?: ReactNode
   firstDayOfWeek?: 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'
   focusedValue?: DateValue | null
   id?: string
   isDateUnavailable?: (DateValue) => boolean
   isDisabled?: boolean = false
   isInvalid?: boolean
   isReadOnly?: boolean = false
   maxValue?: DateValue | null
   minValue?: DateValue | null
   onChange?: (RangeValue<MappedDateValue<DateValue>>) => void
   onFocusChange?: (CalendarDate) => void
   pageBehavior?: PageBehavior = visible
+  selectionAlignment?: 'start' | 'center' | 'end'
   slot?: string | null
   styles?: StylesProp
   value?: RangeValue<DateValue> | null
   visibleMonths?: number = 1

@react-stately/calendar

/@react-stately/calendar:RangeCalendarStateOptions

 RangeCalendarStateOptions <T extends DateValue = DateValue> {
   allowsNonContiguousRanges?: boolean
   autoFocus?: boolean = false
   createCalendar: (CalendarIdentifier) => Calendar
   defaultFocusedValue?: DateValue | null
   defaultValue?: RangeValue<DateValue> | null
   errorMessage?: ReactNode
   firstDayOfWeek?: 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'
   focusedValue?: DateValue | null
   isDateUnavailable?: (DateValue) => boolean
   isDisabled?: boolean = false
   isInvalid?: boolean
   isReadOnly?: boolean = false
   locale: string
   maxValue?: DateValue | null
   minValue?: DateValue | null
   onChange?: (RangeValue<MappedDateValue<DateValue>>) => void
   onFocusChange?: (CalendarDate) => void
   pageBehavior?: PageBehavior = visible
+  selectionAlignment?: 'start' | 'center' | 'end'
   value?: RangeValue<DateValue> | null
   visibleDuration?: DateDuration = {months: 1}
 }

snowystinger
snowystinger reviewed Aug 28, 2025
View reviewed changes
Copy link
Member

@snowystinger snowystinger left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

forgot to finish my review, i'll catch up again later, here were two pending comments. feel free to ignore if they've already been addressed

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

export const RangeCalendarMultiMonthExample: RangeCalendarStory = {
render: (args) => (
<RangeCalendar style={{width: 500}} visibleDuration={{months: 3}} {...args} >
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

styles for this story need a bit of work

it might be useful to add a defaultValue to both examples so that it's more obvious what the alignment is

packages/@react-types/calendar/src/index.d.ts
@@ -66,7 +66,9 @@ export interface CalendarPropsBase {
/**
* The day that starts the week.
*/
firstDayOfWeek?: 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'
firstDayOfWeek?: 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat',
/** Determines how to align the initial selection relative to the visible date range. */
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should changing the selectionAlignment work? or does it only apply on initial render?
maybe something like

Determines the visible months on initial render based on the current selection or current date if there is no selection.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@snowystinger snowystinger snowystinger left review comments

At least 2 approving reviews are required to merge this pull request.

Assignees
No one assigned
Labels
ready for review
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

useRangeCalendarState should allow controlling selectionAlignment
3 participants
@yihuiliao @rspbot @snowystinger