Amazon Developer

Console

as

Settings
Sign out
Notifications
Alexa
Amazon Appstore
AWS
Documentation
Support
Contact Us
My Cases

Console

as

Get Started
Design and Develop
Publish
Reference
Support

Get Started with Vega Carousel

A Carousel is used to implement a single row of content metadata tiles in a Vega application UI screen. Carousels are typically used in home screen grids, in More Like This UIs, and Related Content rows, among other use cases.

  • Fixes to view recycling.
  • Removed layout props like getItemLayout and layoutId because the Carousel now determines the layout automatically.
  • Expanded the list of props to allow for greater customization of the Carousel.
  • Added a new callback prop to notify you whenever the current selected item on the Carousel changes.
  • The library is now app bundled rather than system bundled (see the following section for more details).

App bundled

This version of Carousel is app bundled, which requires an npm update before releases to make sure you have the latest version. App bundling gives you more control of when you bring in new Carousel changes to your app.

Property grouping

The itemStyle and animationDuration props can now be grouped with other props.

Example:

Copied to clipboard.


 <View style={[CAROUSEL_STYLE.container]}>
      <Carousel
        containerStyle={CAROUSEL_STYLE.verticalCarouselContainerStyle}
        orientation={'vertical'}
        itemStyle={{itemPadding: 20}}
        animationDuration={{itemScrollDuration: 0.2}}
        renderItem={renderItemHandler}
        getItemKey={getItemKeyHandler}
        getItem={getItem}
        getItemCount={getItemCount}
        notifyDataError={notifyDataError}
        hasPreferredFocus
        hideItemsBeforeSelection={false}
        selectionStrategy={'anchored'}
        numOffsetItems={2}
        renderedItemsCount={11}
        itemScrollDelay={0.2}
      />
    </View>

Copied to clipboard.

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

Examples

This example demonstrates a basic horizontal carousel implementation with focus states and image rendering. The component uses the dataAdapter pattern to manage item retrieval and includes scale animations for a pressed and selected item.

Copied to clipboard.


import React, { useCallback } from 'react';
import { Image, Pressable, View } from 'react-native';
import {
  Carousel,
  CarouselRef,
  CarouselRenderInfo,
  ItemInfo,
} from '@amazon-devices/vega-carousel';
import { Ref, forwardRef, useImperativeHandle, useRef, useState } from 'react';

import { ItemType, ScrollableProps } from '../../Types';
import { CAROUSEL_STYLE } from './Style';

/**
 * A Horizontal scrollable is a wrapper around the Carousel component. It
 * maintains the same functionality as the Carousel but orients it to display
 * items in a horizontal direction.
 * @param data - Data source
 * @param ref - reference to access Imperative handler methods
 * @returns HorizontalScrollable
 */
export const HorizontalScrollable = forwardRef(
  ({ data }: ScrollableProps, ref?: Ref<CarouselRef<any>>) => {
    const scrollableRef = useRef<CarouselRef<any>>(null);

    function ItemView({
      item,
      index,
    }: CarouselRenderInfo<ItemType>): JSX.Element {
      const [focus, setFocus] = useState<boolean>(false);
      const onFocusHandler = () => {
        setFocus(true);
      };
      const onBlurHandler = () => {
        setFocus(false);
      };

      return (
        <Pressable
          style={[
            CAROUSEL_STYLE.itemHorizontalContainer,
          ]}
          onFocus={onFocusHandler}
          onBlur={onBlurHandler}>
          <Image
            style={CAROUSEL_STYLE.imageContainer}
            source={{ uri: item.url }}
          />
        </Pressable>
      );
    }

    const renderItemhandler = ({ item, index }: CarouselRenderInfo<ItemType>) => {
      return <ItemView index={index} item={item} />;
    };

    const itemInfo: ItemInfo[] = [
      {
        view: ItemView,
        dimension: {
          width: 250,
          height: 420,
        },
      },
    ];

    useImperativeHandle(ref, () => scrollableRef.current!, []);

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

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

    const getItemCount = useCallback(() => {
      const count = data.length;
      console.info('getItemCount called, returning:', count);
      return count;
    }, [data]);

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

    const onSelectionChanged = (event: any) => {
      console.info('Selection changed:', event);
    };

    const focusedItemScaleFactor = 1.1;
    const getSelectedItemOffset = (info: any) => {
      return {
        width: focusedItemScaleFactor,
        height: focusedItemScaleFactor
      };
    };

    return (
      <View style={CAROUSEL_STYLE.container}>
        <Carousel
          ref={scrollableRef}
          dataAdapter={{
            getItem,
            getItemCount,
            getItemKey: keyProviderHandler,
            notifyDataError
          }}
          renderItem={renderItemhandler}
          testID="horizontal-carousel"
          uniqueId="horizontal-carousel-unique"
          orientation={'horizontal'}
          renderedItemsCount={12}
          numOffsetItems={2}
          navigableScrollAreaMargin={100}
          hasPreferredFocus={true}
          initialStartIndex={0}
          hideItemsBeforeSelection={false}
          trapSelectionOnOrientation={false}
          containerStyle={CAROUSEL_STYLE.horizontalCarouselContainerStyle}
          itemStyle={{
            itemPadding: 20,
            itemPaddingOnSelection: 20,
            pressedItemScaleFactor: 0.9,
            selectedItemScaleFactor: focusedItemScaleFactor,
            getSelectedItemOffset: getSelectedItemOffset,
          }}
          animationDuration={{
            itemPressedDuration: 0.15,
            itemScrollDuration: 0.2,
            containerSelectionChangeDuration: 0.25
          }}
          selectionStrategy="natural"
          pinnedSelectedItemOffset="start"
          onSelectionChanged={onSelectionChanged}
          selectionBorder={{
            borderStrategy: 'outset',
          }}
        />
      </View>
    );
  },
);

This example shows how to configure a vertical scrolling carousel with custom selection borders. The implementation includes red border styling with yellow stroke effects and uses the anchored selection strategy to keep items locked during navigation.

Copied to clipboard.


import { Image, Pressable } from 'react-native';
import {
  Carousel,
  CarouselRenderInfo,
  ItemInfo,
} from '@amazon-devices/vega-carousel';
import { useCallback, useState } from 'react';
import React from 'react';
import { ItemType, ScrollableProps } from '../../Types';
import { CAROUSEL_STYLE } from './Style';

/**
 * A vertical scrollable is a wrapper around the Carousel component that
 * allows vertical scrolling. It maintains the same functionality as the
 * Carousel but orients it to display items in a vertical direction.
 * @param data - Data source
 * @returns Vertical Scrollable
 */
export const VerticalScrollable = ({ data }: ScrollableProps) => {
  function ItemView({ item, index }: CarouselRenderInfo<ItemType>): JSX.Element {
    const [focus, setFocus] = useState<boolean>(false);
    const onFocusHandler = () => {
      setFocus(true);
    };
    const onBlurHandler = () => {
      setFocus(false);
    };
    return (
      <Pressable
        style={[
          CAROUSEL_STYLE.itemVerticalContainer,
        ]}
        onFocus={onFocusHandler}
        onBlur={onBlurHandler}>
        <Image style={CAROUSEL_STYLE.imageContainer} source={{ uri: item.url }} />
      </Pressable>
    );
  }

  const renderItemhandler = ({ item, index }: CarouselRenderInfo<ItemType>) => {
    return <ItemView index={index} item={item} />;
  };

  const itemInfo: ItemInfo[] = [
    {
      view: ItemView,
      dimension: {
        width: 250,
        height: 420,
      },
    },
  ];

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

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

  const getItemCount = useCallback(() => {
    const count = data.length;
    console.info('getItemCount called, returning:', count);
    return count;
  }, [data]);

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

  const onSelectionChanged = (event: any) => {
    console.info('Selection changed:', event);
  };

  const getSelectedItemOffset = (info: any) => {
    // Do nothing
    return undefined;
  };

  return (
    <Carousel
      dataAdapter={{
        getItem,
        getItemCount,
        getItemKey: keyProviderHandler,
        notifyDataError
      }}
      renderItem={renderItemhandler}
      testID="vertical-carousel"
      uniqueId="vertical-carousel-unique"
      orientation={'vertical'}
      renderedItemsCount={11}
      numOffsetItems={2}
      navigableScrollAreaMargin={0}
      hasPreferredFocus={false}
      initialStartIndex={0}
      hideItemsBeforeSelection={false}
      trapSelectionOnOrientation={false}
      containerStyle={CAROUSEL_STYLE.verticalCarouselContainerStyle}
      itemStyle={{
        itemPadding: 10,
        itemPaddingOnSelection: 20,
        pressedItemScaleFactor: 0.8,
        selectedItemScaleFactor: 1,
        getSelectedItemOffset: getSelectedItemOffset,
      }}
      animationDuration={{
        itemPressedDuration: 0.18,
        itemScrollDuration: 0.2,
        containerSelectionChangeDuration: 0.22
      }}
      selectionStrategy="anchored"
      pinnedSelectedItemOffset="start"
      onSelectionChanged={onSelectionChanged}
      selectionBorder={{
        borderStrategy: 'outset',
        borderColor: 'red',
        borderWidth: 5,
        borderRadius: 10,
        borderStrokeRadius: 5,
        borderStrokeColor: 'yellow',
        borderStrokeWidth: 2,
      }}
    />
  );
};

This example showcases the Carousel's ability to render different item types within a single row by alternating between two distinct layouts based on index. Items at even indices use a 200px width layout, while odd indices use a 500px width layout, demonstrating flexible content presentation.

Copied to clipboard.


import { Image, Pressable, View } from 'react-native';
import {
  Carousel,
  CarouselRenderInfo,
  ItemInfo,
} from '@amazon-devices/vega-carousel';
import { useCallback, useState } from 'react';
import React from 'react';
import { ItemType, ScrollableProps } from '../../Types';
import { CAROUSEL_STYLE } from './Style';

/**
 * HetrogeneousItemViewScrollable showcases the Carousel's ability to have
 * different UI Item on a single scrollable row.
 * @param data - Data source
 * @returns HetrogeneousItemViewScrollable
 */
export const HetrogeneousItemViewScrollable = ({ data }: ScrollableProps) => {
  function ItemViewType1({
    item,
    index,
  }: CarouselRenderInfo<ItemType>): JSX.Element {
    const [focus, setFocus] = useState<boolean>(false);

    const onFocusHandler = useCallback(() => setFocus(true), []);
    const onBlurHandler = useCallback(() => setFocus(false), []);

    return (
      <Pressable
        style={[
          CAROUSEL_STYLE.itemContainerType1,
          focus && CAROUSEL_STYLE.itemFocusContainer,
        ]}
        onFocus={onFocusHandler}
        onBlur={onBlurHandler}>
        <Image style={CAROUSEL_STYLE.imageContainer} source={{ uri: item.url }} />
      </Pressable>
    );
  }

  function ItemViewType2({
    item,
    index,
  }: CarouselRenderInfo<ItemType>): JSX.Element {
    const [focus, setFocus] = useState<boolean>(false);

    const onFocusHandler = useCallback(() => setFocus(true), []);
    const onBlurHandler = useCallback(() => setFocus(false), []);
    return (
      <Pressable
        style={[
          CAROUSEL_STYLE.itemContainerType2,
          focus && CAROUSEL_STYLE.itemFocusContainer,
        ]}
        onFocus={onFocusHandler}
        onBlur={onBlurHandler}>
        <Image
          style={CAROUSEL_STYLE.imageContainer}
          resizeMode="cover"
          source={{ uri: item.url }}
        />
      </Pressable>
    );
  }

  const renderItemhandler = ({ item, index }: CarouselRenderInfo<ItemType>) => {
    return index % 2 === 0 ? (
      <ItemViewType1 index={index} item={item} />
    ) : (
      <ItemViewType2 index={index} item={item} />
    );
  };

  const itemInfo: ItemInfo[] = [
    {
      view: ItemViewType1,
      dimension: {
        width: CAROUSEL_STYLE.itemContainerType1.width,
        height: CAROUSEL_STYLE.itemContainerType1.height,
      },
    },
    {
      view: ItemViewType2,
      dimension: {
        width: CAROUSEL_STYLE.itemContainerType2.width,
        height: CAROUSEL_STYLE.itemContainerType2.height,
      },
    },
  ];

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

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

  const getItemCount = useCallback(() => {
    const count = data.length;
    console.info('getItemCount called, returning:', count);
    return count;
  }, [data]);

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

  const onSelectionChanged = (event: any) => {
    console.info('Selection changed:', event);
  };

  const selectedItemScaleFactor = 1.1;
  const getSelectedItemOffset = (info: any) => {
    return {
      width: selectedItemScaleFactor,
      height: selectedItemScaleFactor
    };
  };

  return (
    <View style={CAROUSEL_STYLE.container}>
      <Carousel
        dataAdapter={{
          getItem,
          getItemCount,
          getItemKey: keyProviderHandler,
          notifyDataError
        }}
        renderItem={renderItemhandler}
        testID="heterogeneous-carousel"
        uniqueId="heterogeneous-carousel-unique"
        orientation={'horizontal'}
        renderedItemsCount={12}
        numOffsetItems={2}
        navigableScrollAreaMargin={100}
        hasPreferredFocus={false}
        initialStartIndex={0}
        hideItemsBeforeSelection={false}
        trapSelectionOnOrientation={false}
        containerStyle={CAROUSEL_STYLE.horizontalCarouselContainerStyle}
        itemStyle={{
          itemPadding: 40,
          itemPaddingOnSelection: 40,
          pressedItemScaleFactor: 0.9,
          selectedItemScaleFactor: selectedItemScaleFactor,
          getSelectedItemOffset: getSelectedItemOffset,
        }}
        animationDuration={{
          itemPressedDuration: 0.15,
          itemScrollDuration: 0.2,
          containerSelectionChangeDuration: 0.25
        }}
        selectionStrategy="anchored"
        pinnedSelectedItemOffset="start"
        onSelectionChanged={onSelectionChanged}
        selectionBorder={{
          borderStrategy: 'inset',
          borderColor: 'white',
          borderWidth: 4,
          borderRadius: 8,
          borderStrokeRadius: 4,
          borderStrokeColor: 'black',
          borderStrokeWidth: 2,
        }}
      />
    </View>
  );
};

Style

This stylesheet example defines styling constants for a carousel component that supports both horizontal and vertical scrolling orientations. It includes container styles for the main carousel (full-screen with black background), item containers in two size variations (200px and 500px wide), and orientation-specific layouts with fixed dimensions (420px height for horizontal, 250px width for vertical).

Copied to clipboard.


import { StyleSheet } from 'react-native';

export const CAROUSEL_STYLE = StyleSheet.create({
  container: {
    backgroundColor: '#000000',
    width: '100%',
    height: '100%',
    justifyContent: 'center',
    alignItems: 'center',
  },
  imageContainer: {
    width: '100%',
    height: '100%',
    resizeMode: 'cover',
  },
  itemHorizontalContainer: {
    width: 250,
    height: '100%',
  },
  itemVerticalContainer: {
    width: '100%',
    height: 420,
  },
  itemContainerType1: {
    height: 420,
    width: 200,
    justifyContent: 'center',
    alignContent: 'center',
  },
  itemContainerType2: {
    height: 420,
    width: 500,
    justifyContent: 'center',
    alignContent: 'center',
  },
  horizontalCarouselContainerStyle: {
    width: '100%',
    height: 420,
  },
  verticalCarouselContainerStyle: {
    height: '100%',
    width: 250,
    justifyContent: 'center',
  },
});

Custom types

The following examples shows you the custom types that you can use to define carousel items and props for the scrollable wrapper components.

  • ItemType: A custom data type that represents the structure of individual carousel items.

    Properties: The url (string) property is the image URL that is displayed in the carousel item. The url (string) property defines the items passed to the carousel, CarouselRenderInfo<ItemType>, and ScrollableProps.

    Copied to clipboard.

    export type ItemType = {
  url: string;
};

  • ScrollableProps: Props interface for the scrollable carousel wrapper components.

    Properties: The data (ItemType[]) property is an array of item objects to be rendered in the carousel. The data (ItemType[]) property provides type safety for the component props in the Horizontal, Vertical, and Heterogeneous scrollable wrapper components. This ensures the data passed to these components matches the expected structure.

    Copied to clipboard.

    export type ScrollableProps = {
  data: ItemType[];
};

Features

Data adapter

Vega Carousel supports more customization by allowing you to provide a dataAdapter containing various callback functions. For more information, see the Carousel item data adapter callback functions section.

Assuming you have an array called data containing the Carousel item information, you can implement the dataAdapter functions as shown in the following example.

Copied to clipboard.


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
  dataAdapter={{
    getItem,
    getItemCount,
    getItemKey: getItemKeyHandler,
    notifyDataError
  }}
  itemStyle={{itemPadding: 20}}
 />

Selection Strategy

The SelectionStrategy prop controls how a list scrolls and repositions its items when you navigate through them using the D-pad.

Anchored

The anchored style causes the selected item to stay locked on the initial item’s position. When scrolling, the items reposition so that the selected item remains anchored to that position.

Natural

The natural style causes the selected item to move in the direction of the Carousel's orientation until it reaches the start or end of the list.

Pinned

The pinned style pins the selected item at a specified position during scrolling for larger sets of items. As your user approaches the beginning or end of the list, the scroll behavior transitions smoothly into the natural flow.

The optional prop pinnedSelectedItemOffset allows you to define the pin location for the selected item when the SelectionStrategy is pinned.

The pinnedSelectedItemOffset prop determines where the selected item stays fixed (or 'pinned') in the Carousel's viewport. You can specify this position in two ways:

  • As a percentage (0-100%) of the viewport's size:
    • For vertical Carousels: percentage of height
    • For horizontal Carousels: percentage of width
  • Using preset values:
    • start (equals 0%)
    • center (equals 50%)
    • end (equals 100%)

In horizontal mode, measurements are from the left edge, except for right-to-left languages.

Variable Scroll Speed

The Carousel component introduces a novel feature for controlling scroll speed through several AnimationDurationProps. Unlike existing components, such as Flatlist or Flashlist, this feature offers enhanced flexibility, so you can fine-tune the scrolling experience.

The itemPressedDuration prop controls the animation duration when pressing on a Carousel item. The itemScrollDuration prop controls the animation duration used to scroll to each Carousel item. The containerSelectionChangeDuration prop controls the animation duration when changing the selected Carousel container.

Selection Border

The Carousel component supports displaying a border around a UI item when selected. You can style the border and choose how to draw the content and border for the selected item. You can enable the border by defining the selectionBorder prop. The default props for the selection border are shown in the following example.

Copied to clipboard.


{
   borderStrategy: 'outset',
   borderColor: 'white',
   borderWidth: 8,
   borderRadius: 8,
   borderStrokeWidth: 3,
   borderStrokeRadius: 4,
   borderStrokeColor: 'black',
}

Vega Carousel supports the borderStrategy prop. The prop supports two types of strategies:

  • outset - where the border is drawn outside of the original bounds of the item, so the item’s content size remains the same but the overall item size gets bigger.
  • inset - where the border is drawn within the bounds of the item over the item's content, so while the item's content size remains the same, part of the item's content is cropped by the border. The overall item size remains the same.

Props

Prop Type Default Required Details
dataAdapter CarouselItemDataAdapter<ItemT, KeyT> - TRUE The dataAdapter property contains references to four user-defined callback functions that the Carousel calls to access your items: getItem, getItemCount, getItemKey, and notifyDataError. For more information about the callbacks, see Carousel item data adapter callback functions.
renderItem (info: CarouselRenderInfo) => React.ReactElement null TRUE A reference to a user-defined method that renders a carousel item.
testID string undefined FALSE An unique identifer to locate this carousel in end-to-end tests.
uniqueId string undefined FALSE An arbitrary and unique identifier for this carousel that is used to determine when to recycle the carousel and its items. Commonly used by horizontal carousels within a vertical carousel (for example, nested carousels).
orientation horizontal, vertical horizontal FALSE Specifies the direction and layout for rendering items in a carousel.
renderedItemsCount number 8 FALSE The number of items to render at a given time when recycling through the carousel for performance optimization.
numOffsetItems number 2 FALSE Number of items to keep to the top/left of the carousel before recycling the item component to the end.
navigableScrollAreaMargin number 0 FALSE The margin space (in density-independent pixels) on either side of the carousel's navigable content area in the direction of the carousel's orientation (for example, left and right for horizontal carousels, top and bottom for vertical carousels).
hasPreferredFocus boolean FALSE FALSE Determines whether this component should automatically receive focus when rendered.
initialStartIndex number 0 FALSE Specifies the first item index in the carousel to select.
hideItemsBeforeSelection boolean FALSE FALSE Determines whether items before the selected one should be hidden.
trapSelectionOnOrientation boolean FALSE FALSE This flag prevents selection from progressing to the nearest component outside the carousel alongside its orientation. If the carousel is horizontal and the user is at the start item and presses to move backward, or at the end item and presses to move forward, this flag prevents selection from escaping the carousel.
containerStyle StyleProp<ViewStyle> undefined FALSE Style applied to the carousel container.
itemStyle CarouselItemStyleProps - FALSE Style applied to the carousel items.
animationDuration AnimationDurationProps - FALSE The durations of various animations related to the carousel and its items. For more information, see the Animation duration props section.
selectionStrategy anchored, natural, pinned anchored FALSE Specifies how the selected item moves in the carousel in response to the D-pad key presses.
anchored - Causes the selected item to stay anchored on the initial item’s position when scrolling in either direction along the orientation.
natural - Causes the selected item to float along the carousel's orientation until it reaches either end of the list.
pinned - Enables the selected item to follow natural scrolling behavior at the start and end of the list, while keeping it pinned to a specific position defined by the pinnedSelectedItemOffset prop during the rest of the scrolling.
pinnedSelectedItemOffset Percentage start, center, end 0% FALSE The value determines the relative position from the leading edge of the carousel where the selected item is pinned.
onSelectionChanged (event: CarouselSelectionChangeEvent) => void undefined FALSE Function called whenever the current selected item on the list changes (it's not called when the carousel is selected or unselected).
selectionBorder SelectionBorderProps undefined FALSE When set, the selected item has a style-able border that surrounds the selected item. All the style related props in selectionBorder property defines the look-and-feel of the border surrounding the selected item when it is enabled.
ref React.Ref<ShovelerRef<Key>> undefined FALSE When set, provides a reference to the component's methods such as ScrollTo and EnableDPad, which you can call using the reference's current property.

Selection border props

Prop Type Default Required Details
borderStrategy inset, outset outset FALSE Specifies how the content and the border are drawn for the selected item.
borderWidth number 8 FALSE Specifies the thickness of the border around the selected item.
borderColor string white FALSE Specifies the color of the border around the selected item.
borderRadius number 8 FALSE Determines the corner radius of the border for rounded edges.
borderStrokeWidth number 3 FALSE Specifies the thickness of the outline stroke that separates the border from the item's content.
borderStrokeRadius number 4 FALSE Defines the corner radius for the outline stroke that separates the border from the item's content.
borderStrokeColor string black FALSE Specifies the color of the outline stroke for the selection border.

Animation duration props

Prop Type Default Required Details
itemPressedDuration number 0.15 FALSE Amount of time, in seconds, used when pressing on an item.
itemScrollDuration number 0.2 FALSE Amount of time, in seconds, used to scroll each item.
containerSelectionChangeDuration number itemPressedDuration FALSE Amount of time, in seconds, used for changing the selected container.
Prop Type Default Required Details
itemPadding number 20 FALSE The space between the adjacent items along the carousel's orientation, in pixels.
itemPaddingOnSelection number itemPadding FALSE The space between the adjacent items along the carousel's orientation, in pixels when the carousel is selected.
pressedItemScaleFactor number 0.8 FALSE A scale multiplier to be applied to the item when it is pressed by the user.
selectedItemScaleFactor number 1 FALSE A scale multiplier to be applied to the item when it is selected. When this value is 1.0, it means there is no scaling happening to the selected item while the user scrolls through the list.
getSelectedItemOffset (info: CarouselRenderInfo) => ShiftFactor undefined FALSE A function to retrieve the offset value to be applied for an item relative to its current position.
Prop Type Default Required Details
getItem (index: number) => ItemT undefined TRUE A function that receives an index, and returns an item's data object. The object returned is used to call other data-access functions to retrieve information about specific items.
getItemCount () => number; - TRUE A function that returns the item count for the list.
getItemKey (info: CarouselRenderInfo) => KeyT undefined TRUE Function to provide a unique key for each item based on the data and index.
notifyDataError (error: CarouselDataError) => boolean; - TRUE This function is called by the list component when an item cannot be used in the list.

The Carousel component provides methods for programmatic control of the navigation experience. The following methods are accessible by passing an instance of the current component to the ref prop.

Prop Type Default Required Details
scrollTo (index: number, animated : boolean) : void; - FALSE Method to scroll to give Indexed Item on the Carousel.
scrollToKey (key: Key, animated: boolean) : void; - FALSE Method to scroll to the item belonging to a unique key in the Carousel.
enableDpad (enable: boolean) : void; - FALSE Support HW Key events on the Carousel.
notifyDataChange (changes: Array<CarouselDataChange>, animated?: boolean): void - -  

Troubleshooting

Vertical scroll only works with a set height

In the case of vertical scrolling (specifically natural scrolling), you need to set containerStyle with a fixed height value.

Last updated: Feb 09, 2026

Follow us:
amazon_developer_logo

© 2010-2026, Amazon.com, Inc. or its affiliates. All Rights Reserved.

Terms

Amazon Developer Blog

Contact Us