Migrate to the Latest Carousel Version

This article shows you how to migrate to Vega Carousel. If you prefer, you can use Amazon Devices Builder Tools for AI-Powered Development with a compatible AI agent to migrate.

Migrate from VUIC Carousel to Vega Carousel

The following section describes how to migrate from the Carousel that’s included in the Vega UI Component Library to the Vega Carousel that’s available as a separate package.

Migrate props

To use the new version of Carousel, you need to make changes to the props listed below.

Previous Prop	Updated prop	Details
`data` and `dataStartIndex`	-	These props no longer exist. Instead, there are 4 props within the new `dataAdapter` prop that provide the same functionality. Look at the Vega Carousel example for more information.
`rowId`	`uniqueId`	`rowId` was renamed because it’s not specific to rows. `rowId` was also a string instead of a number, which adds flexibility.
`maxToRenderPerBatch`	`renderedItemsCount`	`maxToRenderPerBatch` was renamed because it’s the actual number of items rendered, not the maximum number rendered.
`firstItemOffset`	`navigableScrollAreaMargin`	`firstItemOffset` was renamed because it defines the margin space on either side of the carousel’s navigable content area in the direction of the carousel’s orientation.
`hasTVPreferredFocus`	`hasPreferredFocus`	`hasTVPreferredFocus` was renamed because this functionality is not TV-specific.
`trapFocusOnAxis`	`trapSelectionOnOrientation`	`trapFocusOnAxis` was renamed to align with the `orientation` prop and with using `selection/selected` rather than `focus/focused` because these terms are used interchangeably.
`itemPadding`	`itemStyle`	`itemPadding` is now nested within a new prop called `itemStyle`.
`itemSelectionExpansion`	`selectedItemScaleFactor`	`selectedItemScaleFactor` prop is nested within the `itemStyle` prop. `selectedItemScaleFactor` accepts a number as the scale factor to the item’s size when the item is selected.
`shiftItemsOnSelection`	`getSelectedItemOffset` function	`getSelectedItemOffset`is nested within the `itemStyle` prop. The function returns the width and height of the offset in terms of a scale factor (for example, in proportion to the item’s size).
`focusIndicatorType`	`selectionStrategy`	The `anchored` value of `selectionStrategy` is `fixed` and was renamed to be more descriptive.
`pinnedFocusOffset`	`pinnedSelectedItemOffset`	The potential values of `pinnedSelectedItemOffset` has expanded to include support for `start` , `center` , and `end`. These values correspond to `0%` , `50%` , and `100%` respectively.
`selectionBorder`	-	The `selectionBorder` prop no longer has the `enabled` prop nested within it. The border is enabled as long as the `selectionBorder` prop’s value is defined. The `selectionBorder` prop also has a new nested prop called `borderStrategy`. This prop specifies how the content and the border are drawn for the selected item.
`getItemForIndex` and `itemDimensions`	-	The `getItemForIndex` and `itemDimensions` props have been removed because the carousel now determines the layout automatically for the customer.

Learn more about Vega Carousel and the props it supports.

Import the Vega Carousel package

import { Carousel } from '@amazon-devices/vega-carousel';

Example

The following example demonstrates how to use the Vega Carousel with props.

export function ItemView({ item, index }: CarouselRenderInfo<any>): JSX.Element {
    const [state, setState] = useState(false);
    return (
        <Pressable
            onFocus={() => {
                setState(true)
            }}
            onBlur={() => {
                setState(false)
            }}
            style={[styles.card, state && styles.focus]}
        >
            <View style={[{ flexDirection: 'column' }]}>
                <Image style={styles.image} source={{ uri: item.poster_path }} />
            </View>
        </Pressable>
    );
}

export const renderItem =
    useCallback(({ item, index }: CarouselRenderInfo<any>) => {
        return (
            <ItemView index={index} item={item} />
        );
    }, []);

const getItem = useCallback((index: number) => {
    if (index >= 0 && index < data.length) {
        return data[index];
    }
    return undefined;
}, [data]);

const getItemCount = useCallback(() => {
    return data.length;
}, [data]);

const getItemKey = (info: CarouselRenderInfo) =>
   `${info.url} ${info.item.index}`

const notifyDataError = (error: any) => {
    return false; // Don't retry
};

<Carousel
   orientation={'horizontal'}
   dataAdapter={{
        getItem,
        getItemCount,
        getItemKey,
        notifyDataError
   }}
   renderItem={renderItem}
   selectionStrategy='anchored'
   testID='Carousel'
   `itemStyle={{
        itemPadding: 0,
        selectedItemScaleFactor: 1.1
   }}`
 />

Migrate to Vega Carousel using the Amazon Devices Builder Tools MCP Server with an AI agent

The Amazon Devices Builder Tools MCP Server helps you migrate from the Carousel that is included in the Vega UI Component Library to the Vega Carousel that is available as a separate package. The package for the Amazon Devices Builder Tools MCP Server is @amazon-devices/amazon-devices-buildertools-mcp. To learn more, see Set Up Amazon Devices Builder Tools for AI-Powered Development.

Prerequisites

AI Agent with MCP support:
- Kiro CLI
- Cursor
- VSCode Copilot
- Claude Code CLI
- Amazon Q IDE
- Amazon Q CLI
- Cline
Vega app project with VUIC Carousel implementation.

Step 1: Install Amazon Devices Builder Tools MCP Server

Run this command in your project directory:

npx @amazon-devices/amazon-devices-buildertools-mcp@latest --init-context

Follow the interactive prompts:

Select your AI agent (for example, 7 for Cline).
Enter Y to automatically update Agent’s MCP settings.
Choose default context document installation path.
Review and merge/update the installed context document.

Step 2: Verify MCP installation

In your AI agent’s chat interface, ask the agent to:

List the tools provided by Amazon Devices Builder Tools MCP Server

The following message is displayed:

 - read_document - Read Vega documentation - list_documents - List available documents - analyze_perfetto_traces - Analyze performance traces

Step 3: Run Carousel migration (natural language)

In your AI agent’s chat interface, ask it to:

Upgrade my MovieCarousel.tsx from Carousel V1 to V2

Or more, specifically ask it to:

Help me migrate /Volumes/workplace/vega-video-sample/src/components/MovieCarousel.tsx from Carousel V1 to V2

Overview of the steps your AI agent automatically performs

Reads the carousel migration workflow from MCP documentation.
Follows the step-by-step migration instructions.
Asks for your approval at each step.

Details of your AI-guided migration process

Your AI agent guides you through the following.

Create backup: YourCarousel_ORIGINAL.tsx.
Update imports: @amazon-devices/kepler-ui-components → @amazon-devices/vega-carousel
Update package.json: Add @amazon-devices/vega-carousel: ~0.1.0
Migrate data access: data prop → dataAdapter with functions.
Migrate all props: VUICL Vega props → Vega Carousel equivalent props.
Update logic: onFocus → onSelectionChanged (if applicable).
Clean up: Remove unused VUIC Carousel code.

Step 4: Install dependencies

After the migration completes, to download the @amazon-devices/vega-carousel package, run the following command.

npm install

Step 5: Build and test

To build, use the following command.
npm run build
To run, use the follow command.
npm test

Expected results

Build succeeds.
Tests pass (You might need snapshot updates with npm test -- -u).
No linting errors.

Example: Cline migration session

Ask the agent to:

Upgrade my MovieCarousel.tsx from Carousel V1 to V2

Cline responds with the following.

Reads carousel.md workflow from MCP.
Creates backup file.
Proposes changes step-by-step.
Asks for approval before each modification.
Completes migration automatically.

After you approve each step, run the following commands.

npm install

npm run build

Result: VUIC Carousel is successfully migrated to Vega Carousel.

Common issues and solutions

Remove unused variables

Cause: VUIC Carousel variables (viewInfos, getViewForIndex) no longer needed. Solution: Ask AI: “Remove unused variables from the migration.”

Inline style warnings

Cause: itemStyle object passed inline. Solution: Ask AI: “Extract itemStyle to constants.”

Snapshot tests fail

Cause: Component structure changed. Solution: Run npm test -- -u to update snapshots.

Migration validation

After migration, verify the following.

Imports updated: Check @amazon-devices/vega-carousel in imports.
Package.json updated: Both packages present (vega-carousel + kepler-ui-components for other components).
Backup created: *_ORIGINAL.tsx files exist.
Build succeeds: npm run build passes.
Tests pass: npm test passes.

Key migration changes

VUIC Carousel Prop	Vega Carousel Prop	Change
`data`	`dataAdapter`	Now uses functions: `getItem`, `getItemCount`, `getItemKey`, `notifyDataError`.
`keyProvider`	`getItemKey` (in `dataAdapter`)	Wrapped in dataAdapter object.
`maxToRenderPerBatch`	`renderedItemsCount`	Name change only.
`itemPadding`	`itemStyle.itemPadding`	Nested in `itemStyle` object.
`itemSelectionExpansion`	`itemStyle.selectedItemScaleFactor`	Nested + name change.
`focusIndicatorType`	`selectionStrategy`	Name change: fixed→anchored.
`pinnedFocusOffset`	`pinnedSelectedItemOffset`	Name change + supports start/center/end.
`hasTVPreferredFocus`	`hasPreferredFocus`	Name change (platform-agnostic).
`trapFocusOnAxis`	`trapSelectionOnOrientation`	Name change.
`itemScrollDelay`	`animationDuration.itemScrollDuration`	Nested in `animationDuration`.
None	`onSelectionChanged`	NEW: Direct selection callback.
None	`itemStyle.itemPaddingOnSelection`	NEW: Dynamic spacing on focus.
None	`itemStyle.pressedItemScaleFactor`	NEW: Press feedback.
None	`navigableScrollAreaMargin`	NEW: Scroll area margins.

How to set up supported AI agents using MCP

The following supported AI agents are linked to the corresponding MCP setup instructions.

Success criteria

All Carousel files migrated.
Build passes without errors.
Tests pass (snapshots updated if needed).
No new linting errors introduced.
Backup files created for rollback.

Vega Libraries and Services

Migrate to the Latest Carousel Version

Migrate from VUIC Carousel to Vega Carousel

Migrate props

Import the Vega Carousel package

Example

Migrate to Vega Carousel using the Amazon Devices Builder Tools MCP Server with an AI agent

Prerequisites

Step 1: Install Amazon Devices Builder Tools MCP Server

Step 2: Verify MCP installation

Step 3: Run Carousel migration (natural language)

Overview of the steps your AI agent automatically performs

Details of your AI-guided migration process

Step 4: Install dependencies

Step 5: Build and test

Example: Cline migration session

Common issues and solutions

Remove unused variables

Inline style warnings

Snapshot tests fail

Migration validation

Key migration changes

How to set up supported AI agents using MCP

Success criteria

Support

​Migrate from VUIC Carousel to Vega Carousel

​Migrate props

​Import the Vega Carousel package

​Example

​Migrate to Vega Carousel using the Amazon Devices Builder Tools MCP Server with an AI agent

​Prerequisites

​Step 1: Install Amazon Devices Builder Tools MCP Server

​Step 2: Verify MCP installation

​Step 3: Run Carousel migration (natural language)

​Overview of the steps your AI agent automatically performs

​Details of your AI-guided migration process

​Step 4: Install dependencies

​Step 5: Build and test

​Example: Cline migration session

​Common issues and solutions

​Remove unused variables

​Inline style warnings

​Snapshot tests fail

​Migration validation

​Key migration changes

​How to set up supported AI agents using MCP

​Success criteria

​Support

Migrate from VUIC Carousel to Vega Carousel

Migrate props

Import the Vega Carousel package

Example

Migrate to Vega Carousel using the Amazon Devices Builder Tools MCP Server with an AI agent

Prerequisites

Step 1: Install Amazon Devices Builder Tools MCP Server

Step 2: Verify MCP installation

Step 3: Run Carousel migration (natural language)

Overview of the steps your AI agent automatically performs

Details of your AI-guided migration process

Step 4: Install dependencies

Step 5: Build and test

Example: Cline migration session

Common issues and solutions

Remove unused variables

Inline style warnings

Snapshot tests fail

Migration validation

Key migration changes

How to set up supported AI agents using MCP

Success criteria

Support