Migrate to the Latest Carousel Version

The following sections show you how to migrate to Vega Carousel from the VUIC Carousel that is included in the Vega UI Component Library. If you prefer, you can use Amazon Devices Builder Tools MCP Server 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 is included in the Vega UI Component Library to the Vega Carousel that is available as a separate package. To streamline the process using AI, see Migrate to Vega Carousel using the Amazon Devices Builder Tools MCP Server with an AI agent.

Migrate props

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

You can learn more about Vega Carousel and the props it also supports here.

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 MCP.

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:

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

Step 2: Verify MCP installation

In your AI agent's chat interface, ask:

List the tools provided by Amazon Devices Builder Tools MCP Server

The following 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:

Upgrade my MovieCarousel.tsx from Carousel V1 to V2

Or more, specifically:

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

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

Details of your AI-guided migration process

Your AI agent guides you through the following.

1. Create backup: YourCarousel_ORIGINAL.tsx.
2. Update imports: @amazon-devices/kepler-ui-components → @amazon-devices/vega-carousel
3. Update package.json: Add @amazon-devices/vega-carousel: ~0.1.0
4. Migrate data access: data prop → dataAdapter with functions.
5. Migrate all props: VUICL Vega props → Vega Carousel equivalent props.
6. Update logic: onFocus → onSelectionChanged (if applicable).
7. 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

1. To build, use the following command.

   Copy code Copied to clipboard.

   npm run build
   

2. To run, use the follow command.

   Copy code Copied to clipboard.

   npm test
   

Expected results

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

Example: Cline migration session

You ask:

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.

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

Key migration changes

How to set up supported AI agents using MCP

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

• Cursor
• Github Copilot
• Claude Code CLI
• Amazon Q IDE Extension
• Amazon Q CLI (Kiro)
• Cline

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.

Support

• Set Up Amazon Devices Builder Tools MCP
• NPM Package
• MCP Protocol

Last updated: Feb 09, 2026