feat(mobile): add initialPage prop to Carousel

packages/common/CHANGELOG.md

@@ -8,6 +8,10 @@ All notable changes to this project will be documented in this file.
 
 <!-- template-start -->
 
+## 9.23.0 ((8/27/2026, 05:05 PM PST))
+
+This is an artificial version bump with no new change.
+
 ## 9.22.1 ((8/25/2026, 02:10 PM PST))
 
 This is an artificial version bump with no new change.

packages/common/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coinbase/cds-common",
-  "version": "9.22.1",
+  "version": "9.23.0",
   "description": "Coinbase Design System - Common",
   "repository": {
     "type": "git",

packages/mcp-server/CHANGELOG.md

@@ -8,6 +8,10 @@ All notable changes to this project will be documented in this file.
 
 <!-- template-start -->
 
+## 9.23.0 ((8/27/2026, 05:05 PM PST))
+
+This is an artificial version bump with no new change.
+
 ## 9.22.1 ((8/25/2026, 02:10 PM PST))
 
 This is an artificial version bump with no new change.

packages/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coinbase/cds-mcp-server",
-  "version": "9.22.1",
+  "version": "9.23.0",
   "description": "Coinbase Design System - MCP Server",
   "repository": {
     "type": "git",

packages/mobile/CHANGELOG.md

@@ -8,6 +8,12 @@ All notable changes to this project will be documented in this file.
 
 <!-- template-start -->
 
+## 9.23.0 (8/27/2026 PST)
+
+#### 🚀 Updates
+
+- Add uncontrolled initialPage prop to Carousel. [[#864](https://github.com/coinbase/cds/pull/864)]
+
 ## 9.22.1 (8/25/2026 PST)
 
 #### 🐞 Fixes

packages/mobile/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coinbase/cds-mobile",
-  "version": "9.22.1",
+  "version": "9.23.0",
   "description": "Coinbase Design System - Mobile",
   "repository": {
     "type": "git",

packages/mobile/src/carousel/Carousel.tsx

@@ -3,6 +3,7 @@ import React, {
   useCallback,
   useEffect,
   useImperativeHandle,
+  useLayoutEffect,
   useMemo,
   useRef,
   useState,
@@ -188,6 +189,12 @@ export type CarouselBaseProps = SharedProps &
      * @default 'page'
      */
     snapMode?: 'item' | 'page';
+    /**
+     * Zero-based page index to show on first layout, with no animation. Uncontrolled —
+     * updating it later does not move the carousel. Out-of-range values are clamped.
+     * @default 0
+     */
+    initialPage?: number;
     /**
      * Hides the navigation arrows (previous/next buttons).
      */
@@ -563,6 +570,7 @@ export const Carousel = memo(
       paginationVariant,
       drag = 'snap',
       snapMode = 'page',
+      initialPage,
       NavigationComponent = DefaultCarouselNavigation,
       PaginationComponent = DefaultCarouselPagination,
       style,
@@ -581,13 +589,14 @@ export const Carousel = memo(
       ...props
     } = mergedProps;
     const carouselScrollX = useRef(0);
+    const hasAppliedInitialPageRef = useRef(false);
 
     const animationApi = useSpring({
       x: carouselScrollX.current,
       config: animationConfig,
     });
 
-    const [activePageIndex, setActivePageIndex] = useState(0);
+    const [activePageIndex, setActivePageIndex] = useState(() => Math.max(0, initialPage ?? 0));
     const [containerSize, onLayout] = useLayout();
     const [carouselItemRects, setCarouselItemRects] = useState<{
       [itemId: string]: Rect;
@@ -766,7 +775,7 @@ export const Carousel = memo(
     });
 
     const goToPage = useCallback(
-      (page: number) => {
+      (page: number, { animate: shouldAnimate = true }: { animate?: boolean } = {}) => {
         const newPage = Math.max(0, Math.min(totalPages - 1, page));
         updateActivePageIndex(newPage);
         updateVisibleCarouselItems(pageOffsets[newPage]);
@@ -777,7 +786,11 @@ export const Carousel = memo(
           : pageOffsets[newPage];
 
         carouselScrollX.current = targetOffset;
-        animationApi.x.start({ to: targetOffset, config: animationConfig });
+        if (shouldAnimate) {
+          animationApi.x.start({ to: targetOffset, config: animationConfig });
+        } else {
+          animationApi.x.set(targetOffset);
+        }
         reset();
       },
       [
@@ -792,6 +805,16 @@ export const Carousel = memo(
       ],
     );
 
+    useLayoutEffect(() => {
+      if (hasAppliedInitialPageRef.current || totalPages === 0) return;
+      hasAppliedInitialPageRef.current = true;
+
+      const targetPage = initialPage ?? 0;
+      if (targetPage > 0) {
+        goToPage(targetPage, { animate: false });
+      }
+    }, [totalPages, initialPage, goToPage]);
+
     useImperativeHandle(
       ref,
       () => ({

packages/mobile/src/carousel/__stories__/Carousel.stories.tsx

@@ -605,6 +605,30 @@ const ImperativeApiExample = () => {
   );
 };
 
+const InitialPageExample = () => {
+  const theme = useTheme();
+
+  return (
+    <Example paddingX={0}>
+      <Carousel
+        initialPage={2}
+        snapMode="page"
+        styles={{
+          root: { paddingHorizontal: theme.space[2] },
+          carousel: { gap: theme.space[2] },
+        }}
+        title="Initial Page (opens on page 3)"
+      >
+        {sampleItems.slice(0, 5).map((item, index) => (
+          <CarouselItem key={`initial-page-${index}`} id={`initial-page-${index}`} width="100%">
+            {item}
+          </CarouselItem>
+        ))}
+      </Carousel>
+    </Example>
+  );
+};
+
 const LoopingExamples = () => {
   const theme = useTheme();
 
@@ -833,6 +857,7 @@ export default function CarouselScreen() {
       <AnimatedPaginationExample />
       <LoopingExamples />
       <AutoplayExample />
+      <InitialPageExample />
     </ExampleScreen>
   );
 }

packages/mobile/src/carousel/__tests__/Carousel.test.tsx

@@ -5,7 +5,12 @@ import { Box } from '../../layout/Box';
 import { VStack } from '../../layout/VStack';
 import { Text } from '../../typography/Text';
 import { DefaultThemeProvider } from '../../utils/testHelpers';
-import { Carousel, type CarouselImperativeHandle, useCarouselContext } from '../Carousel';
+import {
+  Carousel,
+  type CarouselImperativeHandle,
+  type CarouselPaginationComponentProps,
+  useCarouselContext,
+} from '../Carousel';
 import { CarouselItem } from '../CarouselItem';
 
 // Mock react-native-gesture-handler with gesture simulation capabilities
@@ -1529,4 +1534,154 @@ describe('Carousel', () => {
       expect(onChangePage).toHaveBeenCalledWith(0);
     });
   });
+
+  describe('Initial Page', () => {
+    // 8 items at width 200 in a 400px container, snapMode="item" => 7 pages (indices 0-6).
+    const itemCount = 8;
+
+    // Custom pagination that surfaces the active page index for assertions.
+    const ActivePagePagination = ({
+      activePageIndex,
+      totalPages,
+    }: CarouselPaginationComponentProps) => (
+      <Text testID="active-page-index">{`${activePageIndex}/${totalPages}`}</Text>
+    );
+
+    beforeEach(() => {
+      mockGestureHandlers.onStart = undefined;
+      mockGestureHandlers.onUpdate = undefined;
+      mockGestureHandlers.onEnd = undefined;
+      jest.clearAllMocks();
+    });
+
+    it('opens on the provided initialPage without firing onChangePage on mount', async () => {
+      const onChangePage = jest.fn();
+
+      render(
+        <TestCarouselWithItems
+          PaginationComponent={ActivePagePagination}
+          initialPage={3}
+          itemCount={itemCount}
+          onChangePage={onChangePage}
+          snapMode="item"
+        />,
+      );
+
+      await waitFor(() => {
+        expect(screen.getByTestId('active-page-index')).toHaveTextContent('3/7');
+      });
+
+      expect(onChangePage).not.toHaveBeenCalled();
+    });
+
+    it('defaults to the first page when initialPage is omitted', async () => {
+      render(
+        <TestCarouselWithItems
+          PaginationComponent={ActivePagePagination}
+          itemCount={itemCount}
+          snapMode="item"
+        />,
+      );
+
+      await waitFor(() => {
+        expect(screen.getByTestId('active-page-index')).toHaveTextContent('0/7');
+      });
+    });
+
+    it.each`
+      initialPage | expectedIndex | description
+      ${99}       | ${6}          | ${'clamps an initialPage above the last page to the last page'}
+      ${-5}       | ${0}          | ${'clamps a negative initialPage to the first page'}
+    `('$description', async ({ initialPage, expectedIndex }) => {
+      render(
+        <TestCarouselWithItems
+          PaginationComponent={ActivePagePagination}
+          initialPage={initialPage}
+          itemCount={itemCount}
+          snapMode="item"
+        />,
+      );
+
+      await waitFor(() => {
+        expect(screen.getByTestId('active-page-index')).toHaveTextContent(`${expectedIndex}/7`);
+      });
+    });
+
+    it('lets a later imperative goToPage override the initial page', async () => {
+      const onChangePage = jest.fn();
+
+      const TestComponent = () => {
+        const carouselRef = useRef<CarouselImperativeHandle>(null);
+
+        return (
+          <DefaultThemeProvider>
+            <VStack>
+              <Text onPress={() => carouselRef.current?.goToPage(1)} testID="go-to-page-1">
+                Go to Page 1
+              </Text>
+              <Carousel
+                ref={carouselRef}
+                PaginationComponent={ActivePagePagination}
+                initialPage={3}
+                onChangePage={onChangePage}
+                snapMode="item"
+              >
+                {Array.from({ length: itemCount }, (_, index) => {
+                  const itemId = `item-${index}`;
+                  return (
+                    <MockCarouselItem key={itemId} id={itemId} itemIndex={index} width={200}>
+                      <Box height={100} testID={`carousel-item-${itemId}`} width={200}>
+                        <Text>Item {index + 1}</Text>
+                      </Box>
+                    </MockCarouselItem>
+                  );
+                })}
+              </Carousel>
+            </VStack>
+          </DefaultThemeProvider>
+        );
+      };
+
+      render(<TestComponent />);
+
+      await waitFor(() => {
+        expect(screen.getByTestId('active-page-index')).toHaveTextContent('3/7');
+      });
+
+      fireEvent.press(screen.getByTestId('go-to-page-1'));
+
+      await waitFor(() => {
+        expect(screen.getByTestId('active-page-index')).toHaveTextContent('1/7');
+      });
+      expect(onChangePage).toHaveBeenCalledWith(1);
+    });
+
+    it('lets a later drag override the initial page', async () => {
+      const onChangePage = jest.fn();
+
+      render(
+        <TestCarouselWithItems
+          PaginationComponent={ActivePagePagination}
+          initialPage={3}
+          itemCount={itemCount}
+          onChangePage={onChangePage}
+          snapMode="item"
+        />,
+      );
+
+      await waitFor(() => {
+        expect(screen.getByTestId('active-page-index')).toHaveTextContent('3/7');
+      });
+
+      onChangePage.mockClear();
+
+      // Drag toward earlier pages from the seeded page 3.
+      simulateDragGesture(200, 0);
+
+      await waitFor(() => {
+        expect(screen.getByTestId('active-page-index')).toHaveTextContent('2/7');
+      });
+      expect(onChangePage).toHaveBeenCalledWith(2);
+    });
+  });
 });

packages/web/CHANGELOG.md

@@ -8,6 +8,12 @@ All notable changes to this project will be documented in this file.
 
 <!-- template-start -->
 
+## 9.23.0 (8/27/2026 PST)
+
+#### 🚀 Updates
+
+- Add uncontrolled initialPage prop to Carousel. [[#864](https://github.com/coinbase/cds/pull/864)]
+
 ## 9.22.1 (8/25/2026 PST)
 
 #### 🐞 Fixes

packages/web/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coinbase/cds-web",
-  "version": "9.22.1",
+  "version": "9.23.0",
   "description": "Coinbase Design System - Web",
   "repository": {
     "type": "git",