ShortKit React Native SDK — Carousel Navigation API

Android support coming in the next release. The carousel navigation API is currently iOS-only. Android stubs are present but return defaults.

Video Carousel Navigation

Navigate videos within a carousel item using the useShortKitCarousel() hook or imperative commands.

Hook-based Navigation

Access carousel state and imperative controls using useShortKitCarousel():

import { useShortKitCarousel } from '@shortkitsdk/react-native';
import { View, Text, Button } from 'react-native';

function MyCarouselControls() {
  const { activeIndex, videoCount, next, previous, setActiveIndex } = useShortKitCarousel();

  if (activeIndex === null) {
    return null; // no carousel currently active
  }

  return (
    <View style={{ padding: 16 }}>
      <Text style={{ marginBottom: 12 }}>
        {activeIndex + 1} of {videoCount}
      </Text>
      <View style={{ flexDirection: 'row', gap: 8 }}>
        <Button
          title="Previous"
          onPress={previous}
          disabled={activeIndex === 0}
        />
        <Button
          title="Next"
          onPress={next}
          disabled={activeIndex === videoCount - 1}
        />
      </View>
    </View>
  );
}

The hook returns:

• activeIndex: Current video index in the carousel, or null if no carousel is active
• videoCount: Total number of videos in the active carousel
• activeCarouselItem: The full carousel item object, or null if none
• next(): Advance to the next video (returns false at the last index)
• previous(): Go to the previous video (returns false at index 0)
• setActiveIndex(index): Jump to a specific index (returns false if out of range)

Imperative Commands (Inside Overlay Surfaces)

For overlay components that run in isolated React surfaces and cannot access context, use ShortKitCommands directly:

import { ShortKitCommands } from '@shortkitsdk/react-native';
import { Pressable, Text } from 'react-native';

function CarouselOverlay() {
  return (
    <Pressable
      onPress={() => {
        const success = ShortKitCommands.carouselNext();
        if (!success) {
          // already at the last video
        }
      }}
    >
      <Text>Next Video</Text>
    </Pressable>
  );
}

Available carousel commands:

• carouselNext(): Advance to the next video (returns false if already at last index)
• carouselPrevious(): Go to the previous video (returns false if already at index 0)
• carouselSetActiveIndex(index): Jump to a specific index (returns false if out of range)

Completion Event Handling

Use the onCarouselActiveVideoCompleted callback on <ShortKitFeed> to react when a video completes playback:

<ShortKitFeed
  onCarouselActiveVideoCompleted={(event) => {
    console.log(`Video ${event.indexInCarousel} completed in carousel`);

    if (event.wasLast && !event.willAutoAdvance) {
      // Show an "End of carousel" call-to-action
      showEndOfCarouselCTA({
        contentItem: event.contentItem,
        carouselItem: event.carouselItem,
      });
    }
  }}
/>

Event properties:

• surfaceId: Identifier of the overlay surface
• contentItem: The video that just completed
• indexInCarousel: Index of the completed video within the carousel
• carouselItem: The full carousel item
• wasLast: Whether this was the last video in the carousel
• willAutoAdvance: Whether the carousel will automatically advance (always false for the last video)

Behavior Contract

• Boundary returns: next() returns false when already at the last index; previous() returns false at index 0; setActiveIndex() returns false for out-of-range indices.
• Last video loops: The final video loops automatically; it does not advance to the next feed item.
• Completion event only on natural end: onCarouselActiveVideoCompleted fires when a video reaches the end naturally. It does not fire for user-initiated swipes or programmatic navigation.
• Auto-advance: When a non-final video completes, the SDK automatically advances to the next video (same as a user swipe). This behavior is suppressed if the user is mid-drag on the carousel.

Example: End-of-Carousel CTA

Build a custom call-to-action when the carousel reaches its end:

function FeedWithCarouselCTA() {
  const [showCTA, setShowCTA] = useState(false);

  return (
    <>
      <ShortKitFeed
        onCarouselActiveVideoCompleted={(event) => {
          if (event.wasLast) {
            setShowCTA(true);
          }
        }}
      />
      {showCTA && (
        <View style={{ padding: 20, backgroundColor: 'rgba(0,0,0,0.8)' }}>
          <Text style={{ color: 'white', fontSize: 16, marginBottom: 12 }}>
            You've seen all videos in this collection!
          </Text>
          <Button
            title="Explore More"
            onPress={() => {
              setShowCTA(false);
            }}
          />
        </View>
      )}
    </>
  );
}