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.

Vega Carousel updates

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:

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

Import Vega Carousel

import { Carousel } from '@amazon-devices/keplerscript-native-ui-components';

Examples

Horizontal Carousel

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.

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>
    );
  },
);

Vertical Carousel

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.

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,
      }}
    />
  );
};

Heterogeneous Carousel

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.

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. There are 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).

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 show 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, , and ScrollableProps.
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.
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.

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. Screenshot that shows several squares aligned in a row with one square showing a black border. The image says scroll direction with arrows pointing horizontally.

Screenshot that shows several squares aligned in a row with one square showing a black border. The image says scroll direction with arrows pointing horizontally.

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. Screenshot that shows a similar scroll direction graphic, but there are three rows and each row has a different square that has a black border. The image shows the progression of scroll direction in each row, as if to scroll to the right.

Screenshot that shows a similar scroll direction graphic, but there are three rows and each row has a different square that has a black border. The image shows the progression of scroll direction in each row, as if to scroll to the right.

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.

{
   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`	-	`TRUE`	Contains references to four user-defined callback functions that the Carousel calls to access your items: `getItem`, `getItemCount`, `getItemKey`, and `notifyDataError`. For more information on 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`	A unique identifier to locate this carousel in end-to-end tests.
`uniqueId`	string	undefined	`FALSE`	An arbitrary and unique identifier for this carousel that determines 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`	The 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 the selection from escaping the carousel.
`containerStyle`	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 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. The item is 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`	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 rgw `selectionBorder` property defines the look-and-feel of the border surrounding the selected item when it’s enabled.
`ref`	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`	How the content and the border are drawn for the selected item.
`borderWidth`	number	8	`FALSE`	The thickness of the border around the selected item.
`borderColor`	string	white	`FALSE`	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`	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`	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.

Carousel item style props

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’s pressed by the user.
`selectedItemScaleFactor`	number	1	`FALSE`	A scale multiplier to be applied to the item when it’s 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`	Retrieves the offset value to be applied for an item relative to its current position.

Carousel item data adapter callback functions

Prop	Type	Default	Required	Details
`getItem`	`(index: number) => ItemT`	undefined	`TRUE`	Receives an index and returns an item’s data object. The object returned calls other data-access functions to retrieve information about items.
`getItemCount`	`() => number;`	-	`TRUE`	Returns the item count for the list.
`getItemKey`	`(info: CarouselRenderInfo) => KeyT`	undefined	`TRUE`	Provides a unique key for each item based on the data and index.
`notifyDataError`	`(error: CarouselDataError) => boolean;`	-	`TRUE`	Called by the list component when an item can’t be used in the list.

Carousel methods

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`	Scrolls to give Indexed Item on the Carousel.
`scrollToKey`	`(key: Key, animated: boolean) : void;`	-	`FALSE`	Scrolls to the item belonging to a unique key in the Carousel.
`enableDpad`	`(enable: boolean) : void;`	-	`FALSE`	Supports HW Key events on the Carousel.
`notifyDataChange`	-	-

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.

​Vega Carousel updates

​App bundled

​Property grouping

​Import Vega Carousel

​Examples

​Horizontal Carousel

​Vertical Carousel

​Heterogeneous Carousel

​Style

​Custom types

​Features

​Data adapter

​Selection Strategy

​Anchored

​Natural

​Pinned

​Variable Scroll Speed

​Selection Border

​Props

​Selection border props

​Animation duration props

​Carousel item style props

​Carousel item data adapter callback functions

​Carousel methods

​Troubleshooting

​Vertical scroll only works with a set height