From 426b691b79787add35f729c52d94442c99021130 Mon Sep 17 00:00:00 2001
From: Gethin Webster <gethinw@amazon.de>
Date: Fri, 20 Mar 2026 15:51:30 +0100
Subject: [PATCH] feat: Add ability to control first month shown in date range
 picker

---
 package-lock.json                             |   1 +
 pages/date-range-picker/common.tsx            |  20 +++
 .../month-calendar-permutations.page.tsx      |   6 +
 .../date-range-picker/range-calendar.page.tsx |   1 +
 .../year-calendar-permutations.page.tsx       |   6 +-
 .../__snapshots__/documenter.test.ts.snap     |  16 +++
 .../date-range-picker-absolute.test.tsx       |  65 ++++++++++
 .../calendar/__tests__/utils.test.ts          | 119 +++++++++++++++---
 src/date-range-picker/calendar/index.tsx      |   3 +-
 src/date-range-picker/calendar/interfaces.ts  |   1 +
 src/date-range-picker/calendar/utils.ts       |  34 ++++-
 src/date-range-picker/dropdown.tsx            |   5 +-
 src/date-range-picker/index.tsx               |   2 +
 src/date-range-picker/interfaces.ts           |   8 ++
 14 files changed, 260 insertions(+), 27 deletions(-)

diff --git a/package-lock.json b/package-lock.json
index 4a1eea1340..807a0d6b64 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -7,6 +7,7 @@
     "": {
       "name": "@cloudscape-design/components",
       "version": "3.0.0",
+      "hasInstallScript": true,
       "dependencies": {
         "@cloudscape-design/collection-hooks": "^1.0.0",
         "@cloudscape-design/component-toolkit": "^1.0.0-beta",
diff --git a/pages/date-range-picker/common.tsx b/pages/date-range-picker/common.tsx
index 91dc392584..6b3e4f7760 100644
--- a/pages/date-range-picker/common.tsx
+++ b/pages/date-range-picker/common.tsx
@@ -27,6 +27,7 @@ interface DateRangePickerPageSettings {
   disabledDates?: DisabledDate;
   showDisabledReason?: boolean;
   hasValue?: boolean;
+  absoluteMultiGridStartPeriod?: DateRangePickerProps.StartPeriod;
 }
 
 const defaultSettings: Required<DateRangePickerPageSettings> = {
@@ -45,6 +46,7 @@ const defaultSettings: Required<DateRangePickerPageSettings> = {
   disabledDates: 'none',
   showDisabledReason: true,
   hasValue: true,
+  absoluteMultiGridStartPeriod: 'current',
 };
 
 export function useDateRangePickerSettings(
@@ -89,6 +91,7 @@ export function useDateRangePickerSettings(
   const disabledDates = urlParams.disabledDates ?? def('disabledDates');
   const showDisabledReason = parseBoolean(def('showDisabledReason'), urlParams.showDisabledReason);
   const hasValue = parseBoolean(def('hasValue'), urlParams.hasValue);
+  const absoluteMultiGridStartPeriod = urlParams.absoluteMultiGridStartPeriod ?? def('absoluteMultiGridStartPeriod');
   const settings: Required<DateRangePickerPageSettings> = {
     dateOnly,
     monthOnly,
@@ -105,6 +108,7 @@ export function useDateRangePickerSettings(
     disabledDates,
     showDisabledReason,
     hasValue,
+    absoluteMultiGridStartPeriod,
   };
   const setSettings = (settings: DateRangePickerPageSettings) => setUrlParams(settings);
 
@@ -256,6 +260,7 @@ export function Settings({
     disabledDates,
     showDisabledReason,
     hasValue,
+    absoluteMultiGridStartPeriod,
   },
   setSettings,
 }: {
@@ -274,6 +279,7 @@ export function Settings({
   const dateFormatOptions = [{ value: 'iso' }, { value: 'slashed' }, { value: 'long-localized' }];
   const inputDateFormat = [{ value: 'iso' }, { value: 'slashed' }];
   const timeFormatOptions = [{ value: 'hh:mm:ss' }, { value: 'hh:mm' }, { value: 'hh' }];
+  const absoluteMultiGridStartPeriodOptions = [{ value: 'current' }, { value: 'previous' }];
   return (
     <SpaceBetween size="m" direction="horizontal">
       <FormField label="Range selector mode">
@@ -332,6 +338,20 @@ export function Settings({
         />
       </FormField>
 
+      <FormField label="Start period">
+        <Select
+          options={absoluteMultiGridStartPeriodOptions}
+          selectedOption={
+            absoluteMultiGridStartPeriodOptions.find(o => o.value === absoluteMultiGridStartPeriod) ?? null
+          }
+          onChange={({ detail }) =>
+            setSettings({
+              absoluteMultiGridStartPeriod: detail.selectedOption.value as DateRangePickerProps.StartPeriod,
+            })
+          }
+        />
+      </FormField>
+
       <SpaceBetween direction="horizontal" size="s">
         <Checkbox checked={hasValue} onChange={({ detail }) => setSettings({ hasValue: detail.checked })}>
           Has initial value
diff --git a/pages/date-range-picker/month-calendar-permutations.page.tsx b/pages/date-range-picker/month-calendar-permutations.page.tsx
index 1a458e8976..2b9e68f97a 100644
--- a/pages/date-range-picker/month-calendar-permutations.page.tsx
+++ b/pages/date-range-picker/month-calendar-permutations.page.tsx
@@ -36,6 +36,7 @@ const permutations = createPermutations<DateRangePickerCalendarProps>([
     customAbsoluteRangeControl: [undefined],
     timeInputFormat: ['hh:mm:ss'] as const,
     absoluteFormat: ['long-localized'] as const,
+    multiGridStartPeriod: ['current'] as const,
   })),
   // Disabled dates
   {
@@ -45,6 +46,7 @@ const permutations = createPermutations<DateRangePickerCalendarProps>([
     customAbsoluteRangeControl: [undefined],
     timeInputFormat: ['hh:mm:ss'] as const,
     absoluteFormat: ['long-localized'] as const,
+    multiGridStartPeriod: ['current'] as const,
   },
   // Date-only
   {
@@ -54,6 +56,7 @@ const permutations = createPermutations<DateRangePickerCalendarProps>([
     customAbsoluteRangeControl: [undefined],
     timeInputFormat: ['hh:mm:ss'] as const,
     absoluteFormat: ['long-localized'] as const,
+    multiGridStartPeriod: ['current'] as const,
   },
   // Custom control
   {
@@ -62,6 +65,7 @@ const permutations = createPermutations<DateRangePickerCalendarProps>([
     customAbsoluteRangeControl: [() => 'Custom control'],
     timeInputFormat: ['hh:mm:ss'] as const,
     absoluteFormat: ['long-localized'] as const,
+    multiGridStartPeriod: ['current'] as const,
   },
   // Date input formats
   {
@@ -71,6 +75,7 @@ const permutations = createPermutations<DateRangePickerCalendarProps>([
     timeInputFormat: ['hh:mm:ss'] as const,
     dateInputFormat: ['iso', 'slashed'] as const,
     absoluteFormat: ['long-localized'] as const,
+    multiGridStartPeriod: ['current'] as const,
   },
   // Time input formats
   {
@@ -79,6 +84,7 @@ const permutations = createPermutations<DateRangePickerCalendarProps>([
     customAbsoluteRangeControl: [undefined],
     timeInputFormat: ['hh:mm', 'hh'] as const,
     absoluteFormat: ['long-localized'] as const,
+    multiGridStartPeriod: ['current'] as const,
   },
 ]);
 
diff --git a/pages/date-range-picker/range-calendar.page.tsx b/pages/date-range-picker/range-calendar.page.tsx
index f4b93f1241..876ffbe7f8 100644
--- a/pages/date-range-picker/range-calendar.page.tsx
+++ b/pages/date-range-picker/range-calendar.page.tsx
@@ -30,6 +30,7 @@ export default function RangeCalendarScenario() {
           customAbsoluteRangeControl={undefined}
           timeInputFormat="hh:mm:ss"
           absoluteFormat="slashed"
+          multiGridStartPeriod="current"
         />
 
         <Link id="focusable-after">Focusable element after</Link>
diff --git a/pages/date-range-picker/year-calendar-permutations.page.tsx b/pages/date-range-picker/year-calendar-permutations.page.tsx
index 7b0a3888c9..ec571c3590 100644
--- a/pages/date-range-picker/year-calendar-permutations.page.tsx
+++ b/pages/date-range-picker/year-calendar-permutations.page.tsx
@@ -19,7 +19,7 @@ const intervals = [
   ['2022-02', '2022-03'], //next
   ['2021-01', '2021-03'], //q1
   ['2022-04', '2022-06'], //q2
-  ['2023-07', '2022-09'], //q3
+  ['2022-07', '2022-09'], //q3
   ['2024-10', '2024-12'], //q4
 ];
 
@@ -33,6 +33,7 @@ const permutations = createPermutations<DateRangePickerCalendarProps>([
     customAbsoluteRangeControl: [undefined],
     timeInputFormat: ['hh:mm:ss'] as const,
     absoluteFormat: ['long-localized'] as const,
+    multiGridStartPeriod: ['current', 'previous'] as const,
   })),
   // Disabled dates
   {
@@ -42,6 +43,7 @@ const permutations = createPermutations<DateRangePickerCalendarProps>([
     customAbsoluteRangeControl: [undefined],
     timeInputFormat: ['hh:mm:ss'] as const,
     absoluteFormat: ['long-localized'] as const,
+    multiGridStartPeriod: ['current'] as const,
   },
   // Custom control
   {
@@ -50,6 +52,7 @@ const permutations = createPermutations<DateRangePickerCalendarProps>([
     customAbsoluteRangeControl: [() => 'Custom control'],
     timeInputFormat: ['hh:mm:ss'] as const,
     absoluteFormat: ['long-localized'] as const,
+    multiGridStartPeriod: ['current'] as const,
   },
   // Input date formats
   {
@@ -59,6 +62,7 @@ const permutations = createPermutations<DateRangePickerCalendarProps>([
     timeInputFormat: ['hh:mm:ss'] as const,
     dateInputFormat: ['iso', 'slashed'] as const,
     absoluteFormat: ['long-localized'] as const,
+    multiGridStartPeriod: ['current'] as const,
   },
 ]);
 
diff --git a/src/__tests__/snapshot-tests/__snapshots__/documenter.test.ts.snap b/src/__tests__/snapshot-tests/__snapshots__/documenter.test.ts.snap
index 82ee041bc7..778dd080cd 100644
--- a/src/__tests__/snapshot-tests/__snapshots__/documenter.test.ts.snap
+++ b/src/__tests__/snapshot-tests/__snapshots__/documenter.test.ts.snap
@@ -10816,6 +10816,22 @@ It can take the following values:
       "optional": true,
       "type": "string",
     },
+    {
+      "defaultValue": "'current'",
+      "description": "Specifies whether to start with the previous or current period (month or year)
+when multiple calendar grids are displayed in absolute mode.",
+      "inlineType": {
+        "name": "DateRangePickerProps.StartPeriod",
+        "type": "union",
+        "values": [
+          "current",
+          "previous",
+        ],
+      },
+      "name": "absoluteMultiGridStartPeriod",
+      "optional": true,
+      "type": "string",
+    },
     {
       "description": "Adds \`aria-describedby\` to the component. If you're using this component within a form field,
 don't set this property because the form field component automatically sets it.
diff --git a/src/date-range-picker/__tests__/date-range-picker-absolute.test.tsx b/src/date-range-picker/__tests__/date-range-picker-absolute.test.tsx
index b2c7d562e3..713eb38b22 100644
--- a/src/date-range-picker/__tests__/date-range-picker-absolute.test.tsx
+++ b/src/date-range-picker/__tests__/date-range-picker-absolute.test.tsx
@@ -1154,6 +1154,71 @@ describe('Date range picker', () => {
         });
       });
 
+      describe('absoluteMultiGridStartPeriod', () => {
+        test('defaults to "current" - header shows start date period on the left grid', () => {
+          const { wrapper } = renderDateRangePicker({
+            ...defaultProps,
+            granularity,
+            value: { type: 'absolute', startDate: '2020-03-02T05:00:00+08:45', endDate: '2020-03-12T13:05:21+08:45' },
+          });
+
+          wrapper.findTrigger().click();
+
+          // Default "current" means the start date's month/year appears in the left grid
+          // For day: left=March 2020, right=April 2020, header shows "March 2020April 2020"
+          // For month: left=2020, right=2021, header shows "20202021"
+          const expectedResult = granularity === 'day' ? 'March 2020' : '20202021';
+          expect(wrapper.findDropdown()!.findHeader().getElement()).toHaveTextContent(expectedResult);
+        });
+
+        test('"current" explicitly set shows same as default', () => {
+          const { wrapper } = renderDateRangePicker({
+            ...defaultProps,
+            granularity,
+            absoluteMultiGridStartPeriod: 'current',
+            value: { type: 'absolute', startDate: '2020-03-02T05:00:00+08:45', endDate: '2020-03-12T13:05:21+08:45' },
+          });
+
+          wrapper.findTrigger().click();
+
+          const expectedResult = granularity === 'day' ? 'March 2020' : '20202021';
+          expect(wrapper.findDropdown()!.findHeader().getElement()).toHaveTextContent(expectedResult);
+        });
+
+        test('"previous" shows the previous period on the left grid', () => {
+          const { wrapper } = renderDateRangePicker({
+            ...defaultProps,
+            granularity,
+            absoluteMultiGridStartPeriod: 'previous',
+            value: { type: 'absolute', startDate: '2020-03-02T05:00:00+08:45', endDate: '2020-03-12T13:05:21+08:45' },
+          });
+
+          wrapper.findTrigger().click();
+
+          // "previous" means start date's month/year is shown on the right grid, previous on the left
+          // For day: left=February 2020, right=March 2020, header shows "February 2020March 2020"
+          // For month: left=2019, right=2020, header shows "20192020"
+          const expectedResult = granularity === 'day' ? 'February 2020' : '20192020';
+          expect(wrapper.findDropdown()!.findHeader().getElement()).toHaveTextContent(expectedResult);
+        });
+
+        test('"previous" allows start date to be visible in right grid', () => {
+          const { wrapper } = renderDateRangePicker({
+            ...defaultProps,
+            granularity,
+            absoluteMultiGridStartPeriod: 'previous',
+            value: { type: 'absolute', startDate: '2021-06-15T00:00:00+08:45', endDate: '2021-06-20T23:59:59+08:45' },
+          });
+
+          wrapper.findTrigger().click();
+
+          // For day: left=May 2021, right=June 2021
+          // For month: left=2020, right=2021
+          const expectedResult = granularity === 'day' ? 'May 2021' : '20202021';
+          expect(wrapper.findDropdown()!.findHeader().getElement()).toHaveTextContent(expectedResult);
+        });
+      });
+
       describe('i18n', () => {
         describe.each([true, false] as const)('With dateOnly of %s', dateOnly => {
           test('supports using absolute range with i18n defaults', () => {
diff --git a/src/date-range-picker/calendar/__tests__/utils.test.ts b/src/date-range-picker/calendar/__tests__/utils.test.ts
index b0f82e121f..a3c17e1e3d 100644
--- a/src/date-range-picker/calendar/__tests__/utils.test.ts
+++ b/src/date-range-picker/calendar/__tests__/utils.test.ts
@@ -94,40 +94,80 @@ describe('findMonthToDisplay', () => {
   });
   test('should return start date month for single grid', () => {
     const value = { start: { date: '2023-03-15', time: '00:00' }, end: { date: '', time: '' } };
-    const result = findMonthToDisplay(value, true);
+    const result = findMonthToDisplay(value, true, 'current');
     expect(result).toEqual(createDate('2023-03-01'));
   });
-  test('should return next month of start date for double grid', () => {
+  test('should return next month of start date for double grid with startPeriod "current"', () => {
     const value = { start: { date: '2023-03-15', time: '00:00' }, end: { date: '', time: '' } };
-    const result = findMonthToDisplay(value, false);
+    const result = findMonthToDisplay(value, false, 'current');
+    expect(result).toEqual(createDate('2023-04-01'));
+  });
+  test('should return same month of start date for double grid with startPeriod "previous"', () => {
+    const value = { start: { date: '2023-03-15', time: '00:00' }, end: { date: '', time: '' } };
+    const result = findMonthToDisplay(value, false, 'previous');
+    expect(result).toEqual(createDate('2023-03-01'));
+  });
+  test('should keep startPeriod "previous" when range spans 1 month (same month)', () => {
+    const value = { start: { date: '2023-03-10', time: '00:00' }, end: { date: '2023-03-20', time: '00:00' } };
+    const result = findMonthToDisplay(value, false, 'previous');
+    expect(result).toEqual(createDate('2023-03-01'));
+  });
+  test('should override startPeriod "previous" to "current" when range spans more than 1 month', () => {
+    const value = { start: { date: '2023-03-15', time: '00:00' }, end: { date: '2023-04-01', time: '00:00' } };
+    const result = findMonthToDisplay(value, false, 'previous');
+    // Should behave like 'current': left panel shows March, right panel shows April
     expect(result).toEqual(createDate('2023-04-01'));
   });
   test('should return end date month when start date is null', () => {
     const value = { start: { date: '', time: '' }, end: { date: '2023-07-20', time: '00:00' } };
-    const result = findMonthToDisplay(value, true); // isSingleGrid doesn't matter in this case
+    const result = findMonthToDisplay(value, true, 'current'); // isSingleGrid doesn't matter in this case
     expect(result).toEqual(createDate('2023-07-01'));
   });
   test('should return current month when both start and end dates are null', () => {
     const value = { start: { date: '', time: '' }, end: { date: '', time: '' } };
-    const result = findMonthToDisplay(value, true); // isSingleGrid doesn't matter in this case
+    const result = findMonthToDisplay(value, true, 'current'); // isSingleGrid doesn't matter in this case
     expect(result).toEqual(createDate('2023-06-01')); // Based on the mocked current date
   });
   test('should handle leap years correctly', () => {
     jest.setSystemTime(createDate('2024-02-15').getTime());
     const value = { start: { date: '2024-02-29', time: '00:00' }, end: { date: '', time: '' } };
-    const result = findMonthToDisplay(value, true);
+    const result = findMonthToDisplay(value, true, 'current');
     expect(result).toEqual(createDate('2024-02-01'));
   });
-  test('should handle year change for double grid', () => {
+  test('should handle year change for double grid with startPeriod "current"', () => {
     const value = { start: { date: '2023-12-15', time: '00:00' }, end: { date: '', time: '' } };
-    const result = findMonthToDisplay(value, false);
+    const result = findMonthToDisplay(value, false, 'current');
     expect(result).toEqual(createDate('2024-01-01'));
   });
+  test('should not change year for double grid with startPeriod "previous" on December', () => {
+    const value = { start: { date: '2023-12-15', time: '00:00' }, end: { date: '', time: '' } };
+    const result = findMonthToDisplay(value, false, 'previous');
+    expect(result).toEqual(createDate('2023-12-01'));
+  });
+  test('should override startPeriod "previous" when range crosses year boundary and spans more than 2 months', () => {
+    const value = { start: { date: '2023-11-15', time: '00:00' }, end: { date: '2024-03-15', time: '00:00' } };
+    const result = findMonthToDisplay(value, false, 'previous');
+    expect(result).toEqual(createDate('2023-12-01'));
+  });
   test('should prioritize start date over end date', () => {
     const value = { start: { date: '2023-03-15', time: '00:00' }, end: { date: '2023-07-20', time: '00:00' } };
-    const result = findMonthToDisplay(value, true);
+    const result = findMonthToDisplay(value, true, 'current');
     expect(result).toEqual(createDate('2023-03-01'));
   });
+  test('startPeriod has no effect on single grid', () => {
+    const value = { start: { date: '2023-03-15', time: '00:00' }, end: { date: '', time: '' } };
+    const resultCurrent = findMonthToDisplay(value, true, 'current');
+    const resultPrevious = findMonthToDisplay(value, true, 'previous');
+    expect(resultCurrent).toEqual(resultPrevious);
+    expect(resultCurrent).toEqual(createDate('2023-03-01'));
+  });
+  test('startPeriod has no effect when no start date is set', () => {
+    const value = { start: { date: '', time: '' }, end: { date: '2023-07-20', time: '00:00' } };
+    const resultCurrent = findMonthToDisplay(value, false, 'current');
+    const resultPrevious = findMonthToDisplay(value, false, 'previous');
+    expect(resultCurrent).toEqual(resultPrevious);
+    expect(resultCurrent).toEqual(createDate('2023-07-01'));
+  });
 });
 describe('findYearToDisplay', () => {
   beforeEach(() => {
@@ -138,47 +178,86 @@ describe('findYearToDisplay', () => {
   });
   test('should return start year for single grid', () => {
     const value = { start: { date: '2023-03-15', time: '00:00' }, end: { date: '', time: '' } };
-    const result = findYearToDisplay(value, true);
+    const result = findYearToDisplay(value, true, 'current');
     expect(result).toEqual(createDate('2023-01-01'));
   });
-  test('should return next year of start date for double grid', () => {
+  test('should return next year of start date for double grid with startPeriod "current"', () => {
+    const value = { start: { date: '2023-03-15', time: '00:00' }, end: { date: '', time: '' } };
+    const result = findYearToDisplay(value, false, 'current');
+    expect(result).toEqual(createDate('2024-01-01'));
+  });
+  test('should return same year of start date for double grid with startPeriod "previous"', () => {
     const value = { start: { date: '2023-03-15', time: '00:00' }, end: { date: '', time: '' } };
-    const result = findYearToDisplay(value, false);
+    const result = findYearToDisplay(value, false, 'previous');
+    expect(result).toEqual(createDate('2023-01-01'));
+  });
+  test('should keep startPeriod "previous" when range spans 1 year (same year)', () => {
+    const value = { start: { date: '2023-03-15', time: '00:00' }, end: { date: '2023-11-15', time: '00:00' } };
+    const result = findYearToDisplay(value, false, 'previous');
+    expect(result).toEqual(createDate('2023-01-01'));
+  });
+  test('should override startPeriod "previous" to "current" when range spans more than 1 year', () => {
+    const value = { start: { date: '2023-03-15', time: '00:00' }, end: { date: '2024-06-15', time: '00:00' } };
+    const result = findYearToDisplay(value, false, 'previous');
+    expect(result).toEqual(createDate('2024-01-01'));
+  });
+  test('should override startPeriod "previous" to "current" when range spans exactly 3 years', () => {
+    const value = { start: { date: '2023-01-01', time: '00:00' }, end: { date: '2025-12-31', time: '00:00' } };
+    const result = findYearToDisplay(value, false, 'previous');
     expect(result).toEqual(createDate('2024-01-01'));
   });
   test('should return end year when start date is empty', () => {
     const value = { start: { date: '', time: '' }, end: { date: '2024-07-20', time: '00:00' } };
-    const result = findYearToDisplay(value, true); // isSingleGrid doesn't matter in this case
+    const result = findYearToDisplay(value, true, 'current'); // isSingleGrid doesn't matter in this case
     expect(result).toEqual(createDate('2024-01-01'));
   });
   test('should return current year when both start and end dates are empty', () => {
     const value = { start: { date: '', time: '' }, end: { date: '', time: '' } };
-    const result = findYearToDisplay(value, true); // isSingleGrid doesn't matter in this case
+    const result = findYearToDisplay(value, true, 'current'); // isSingleGrid doesn't matter in this case
     expect(result).toEqual(createDate('2023-01-01')); // Based on the mocked current date
   });
   test('should handle leap years correctly', () => {
     const value = { start: { date: '2024-02-29', time: '00:00' }, end: { date: '', time: '' } };
-    const result = findYearToDisplay(value, true);
+    const result = findYearToDisplay(value, true, 'current');
     expect(result).toEqual(createDate('2024-01-01'));
   });
-  test('should handle year change for double grid', () => {
+  test('should handle year change for double grid with startPeriod "current"', () => {
     const value = { start: { date: '2023-12-15', time: '00:00' }, end: { date: '', time: '' } };
-    const result = findYearToDisplay(value, false);
+    const result = findYearToDisplay(value, false, 'current');
     expect(result).toEqual(createDate('2024-01-01'));
   });
+  test('should return same year for double grid with startPeriod "previous" on December', () => {
+    const value = { start: { date: '2023-12-15', time: '00:00' }, end: { date: '', time: '' } };
+    const result = findYearToDisplay(value, false, 'previous');
+    expect(result).toEqual(createDate('2023-01-01'));
+  });
   test('should prioritize start date over end date', () => {
     const value = { start: { date: '2023-03-15', time: '00:00' }, end: { date: '2024-07-20', time: '00:00' } };
-    const result = findYearToDisplay(value, true);
+    const result = findYearToDisplay(value, true, 'current');
     expect(result).toEqual(createDate('2023-01-01'));
   });
   test('should handle end of year dates', () => {
     const value = { start: { date: '2023-12-31', time: '23:59' }, end: { date: '', time: '' } };
-    const result = findYearToDisplay(value, true);
+    const result = findYearToDisplay(value, true, 'current');
     expect(result).toEqual(createDate('2023-01-01'));
   });
   test('should handle start of year dates', () => {
     const value = { start: { date: '2023-01-01', time: '00:00' }, end: { date: '', time: '' } };
-    const result = findYearToDisplay(value, true);
+    const result = findYearToDisplay(value, true, 'current');
     expect(result).toEqual(createDate('2023-01-01'));
   });
+  test('startPeriod has no effect on single grid', () => {
+    const value = { start: { date: '2023-03-15', time: '00:00' }, end: { date: '', time: '' } };
+    const resultCurrent = findYearToDisplay(value, true, 'current');
+    const resultPrevious = findYearToDisplay(value, true, 'previous');
+    expect(resultCurrent).toEqual(resultPrevious);
+    expect(resultCurrent).toEqual(createDate('2023-01-01'));
+  });
+  test('startPeriod has no effect when no start date is set', () => {
+    const value = { start: { date: '', time: '' }, end: { date: '2024-07-20', time: '00:00' } };
+    const resultCurrent = findYearToDisplay(value, false, 'current');
+    const resultPrevious = findYearToDisplay(value, false, 'previous');
+    expect(resultCurrent).toEqual(resultPrevious);
+    expect(resultCurrent).toEqual(createDate('2024-01-01'));
+  });
 });
diff --git a/src/date-range-picker/calendar/index.tsx b/src/date-range-picker/calendar/index.tsx
index 84de2b5adb..da05af8bcc 100644
--- a/src/date-range-picker/calendar/index.tsx
+++ b/src/date-range-picker/calendar/index.tsx
@@ -52,6 +52,7 @@ export default function DateRangePickerCalendar({
   dateInputFormat,
   customAbsoluteRangeControl,
   granularity = 'day',
+  multiGridStartPeriod,
 }: DateRangePickerCalendarProps) {
   const isSingleGrid = useMobile();
   const isMonthPicker = granularity === 'month';
@@ -66,7 +67,7 @@ export default function DateRangePickerCalendar({
   const addPage = isMonthPicker ? addYears : addMonths;
   const startOfPage = isMonthPicker ? startOfYear : startOfMonth;
   const findItemToFocus = isMonthPicker ? findMonthToFocus : findDateToFocus;
-  const [currentPage, setCurrentPage] = useState(() => findPageToDisplay(value, isSingleGrid));
+  const [currentPage, setCurrentPage] = useState(() => findPageToDisplay(value, isSingleGrid, multiGridStartPeriod));
   const [focusedDate, setFocusedDate] = useState<Date | null>(() => {
     if (value.start.date) {
       const startDate = parseDate(value.start.date);
diff --git a/src/date-range-picker/calendar/interfaces.ts b/src/date-range-picker/calendar/interfaces.ts
index 317a3a34a2..07bc0851e4 100644
--- a/src/date-range-picker/calendar/interfaces.ts
+++ b/src/date-range-picker/calendar/interfaces.ts
@@ -55,6 +55,7 @@ export interface DateRangePickerCalendarProps
   value: DateRangePickerProps.PendingAbsoluteValue;
   setValue: React.Dispatch<React.SetStateAction<DateRangePickerProps.PendingAbsoluteValue>>;
   i18nStrings?: RangeCalendarI18nStrings;
+  multiGridStartPeriod: DateRangePickerProps.StartPeriod;
 }
 
 export interface RangeInputsProps
diff --git a/src/date-range-picker/calendar/utils.ts b/src/date-range-picker/calendar/utils.ts
index 0dc45f6b90..dc90e1f680 100644
--- a/src/date-range-picker/calendar/utils.ts
+++ b/src/date-range-picker/calendar/utils.ts
@@ -43,13 +43,26 @@ export function findMonthToFocus(
   return null;
 }
 
-export function findMonthToDisplay(value: DateRangePickerProps.PendingAbsoluteValue, isSingleGrid: boolean) {
+export function findMonthToDisplay(
+  value: DateRangePickerProps.PendingAbsoluteValue,
+  isSingleGrid: boolean,
+  startPeriod: DateRangePickerProps.StartPeriod
+) {
   if (value.start.date) {
     const startDate = parseDate(value.start.date);
     if (isSingleGrid) {
       return startOfMonth(startDate);
     }
-    return startOfMonth(addMonths(startDate, 1));
+
+    let effectiveStartPeriod = startPeriod;
+    if (startPeriod === 'previous' && value.end.date) {
+      const endDate = parseDate(value.end.date);
+      if (!isSameMonth(endDate, startDate)) {
+        effectiveStartPeriod = 'current';
+      }
+    }
+
+    return startOfMonth(addMonths(startDate, effectiveStartPeriod === 'current' ? 1 : 0));
   }
   if (value.end.date) {
     return startOfMonth(parseDate(value.end.date));
@@ -57,13 +70,26 @@ export function findMonthToDisplay(value: DateRangePickerProps.PendingAbsoluteVa
   return startOfMonth(Date.now());
 }
 
-export function findYearToDisplay(value: DateRangePickerProps.PendingAbsoluteValue, isSingleGrid: boolean) {
+export function findYearToDisplay(
+  value: DateRangePickerProps.PendingAbsoluteValue,
+  isSingleGrid: boolean,
+  startPeriod: DateRangePickerProps.StartPeriod
+) {
   if (value.start.date) {
     const startDate = parseDate(value.start.date);
     if (isSingleGrid) {
       return startOfYear(startDate);
     }
-    return startOfYear(addYears(startDate, 1));
+
+    let effectiveStartPeriod = startPeriod;
+    if (startPeriod === 'previous' && value.end.date) {
+      const endDate = parseDate(value.end.date);
+      if (!isSameYear(endDate, startDate)) {
+        effectiveStartPeriod = 'current';
+      }
+    }
+
+    return startOfYear(addYears(startDate, effectiveStartPeriod === 'current' ? 1 : 0));
   }
   if (value.end.date) {
     return startOfYear(parseDate(value.end.date));
diff --git a/src/date-range-picker/dropdown.tsx b/src/date-range-picker/dropdown.tsx
index 521dcac98e..9fc0c45a2b 100644
--- a/src/date-range-picker/dropdown.tsx
+++ b/src/date-range-picker/dropdown.tsx
@@ -52,8 +52,9 @@ interface DateRangePickerDropdownProps
         | 'i18nStrings'
         | 'customRelativeRangeUnits'
         | 'dateDisabledReason'
+        | 'absoluteMultiGridStartPeriod'
       >,
-      'absoluteFormat' | 'timeInputFormat'
+      'absoluteFormat' | 'timeInputFormat' | 'absoluteMultiGridStartPeriod'
     >,
     Pick<CalendarProps, 'granularity'> {
   onClear: () => void;
@@ -91,6 +92,7 @@ export function DateRangePickerDropdown({
   customRelativeRangeUnits,
   renderRelativeRangeContent,
   granularity = 'day',
+  absoluteMultiGridStartPeriod,
 }: DateRangePickerDropdownProps) {
   const i18n = useInternalI18n('date-range-picker');
   const isMonthPicker = granularity === 'month';
@@ -216,6 +218,7 @@ export function DateRangePickerDropdown({
                       dateInputFormat={dateInputFormat}
                       customAbsoluteRangeControl={customAbsoluteRangeControl}
                       granularity={granularity}
+                      multiGridStartPeriod={absoluteMultiGridStartPeriod}
                     />
                   )}
 
diff --git a/src/date-range-picker/index.tsx b/src/date-range-picker/index.tsx
index 3611c166b2..203c7a006a 100644
--- a/src/date-range-picker/index.tsx
+++ b/src/date-range-picker/index.tsx
@@ -117,6 +117,7 @@ const DateRangePicker = React.forwardRef(
       customRelativeRangeUnits,
       renderRelativeRangeContent,
       granularity = 'day',
+      absoluteMultiGridStartPeriod = 'current',
       ...rest
     }: DateRangePickerProps,
     ref: Ref<DateRangePickerProps.Ref>
@@ -359,6 +360,7 @@ const DateRangePicker = React.forwardRef(
                   customRelativeRangeUnits={customRelativeRangeUnits}
                   renderRelativeRangeContent={renderRelativeRangeContent}
                   granularity={granularity}
+                  absoluteMultiGridStartPeriod={absoluteMultiGridStartPeriod}
                 />
               )}
             </ResetContextsForModal>
diff --git a/src/date-range-picker/interfaces.ts b/src/date-range-picker/interfaces.ts
index 3f3a505cf5..1c277f221b 100644
--- a/src/date-range-picker/interfaces.ts
+++ b/src/date-range-picker/interfaces.ts
@@ -213,6 +213,12 @@ export interface DateRangePickerProps
    * Adds `aria-label` to the trigger and dropdown.
    */
   ariaLabel?: string;
+
+  /**
+   * Specifies whether to start with the previous or current period (month or year)
+   * when multiple calendar grids are displayed in absolute mode.
+   */
+  absoluteMultiGridStartPeriod?: DateRangePickerProps.StartPeriod;
 }
 
 export namespace DateRangePickerProps {
@@ -609,6 +615,8 @@ export namespace DateRangePickerProps {
   export type DateInputFormat = EditableDateFormat | undefined;
 
   export type TimeInputFormat = TimeInputProps.Format;
+
+  export type StartPeriod = 'previous' | 'current';
 }
 
 export type DayIndex = 0 | 1 | 2 | 3 | 4 | 5 | 6;