Video carousel

A video carousel is a horizontally-swipeable collection of short videos within a single feed cell. The SDK owns the pager, the player handoff between pages, and the transition animations natively. This page covers the APIs you use to observe the active carousel, navigate it programmatically, and react to video completions. To render the chrome (titles, page indicators, action buttons) on top of the native pager, see Overlays › Video carousel overlays. For the VideoCarouselItem data shape, see Content Types › Video carousel.

Default behavior

When the current feed item is a video carousel, the SDK applies these rules automatically — no configuration required.

Trigger	Behavior
The carousel becomes visible for the first time	The SDK lands on the carousel’s `initialPageIndex` (defaults to `0`) without a horizontal scroll animation. See Video carousel › `initialPageIndex` for the data shape.
The user swipes vertically away from the carousel and back	The carousel resets to `initialPageIndex` again. Last-watched position is not preserved.
A video in the carousel plays to its natural end	The SDK advances to the next video in the carousel and fires a completion event.
The last video in the carousel plays to its natural end	The SDK loops that last video back to itself. The feed does not advance to the next feed item. A completion event fires with `wasLast: true` and `willAutoAdvance: false`.
The user swipes horizontally, or your code calls an imperative method	The active video is paused and the target video begins playback. No completion event fires — completion is reserved for natural-end transitions.
The user swipes vertically and the feed settles on a non-carousel item	Reactive state (`activeIndex`, `activeCarouselItem`) clears to `nil` / `null`.

Imperative methods move the active carousel without a user gesture. All three return a boolean indicating whether the command was accepted. These methods are scoped to the current carousel — they page between videos inside a single VideoCarouselItem. They are distinct from the feed-scoped shortKit.player.skipToNext() / ShortKitCommands.skipToNext(), which navigate between feed items (including across carousels).

Declarative landing vs. imperative jump. setActiveIndex(_:) is for moving within an already-active carousel — for example, in response to a button tap inside an overlay. To land on a specific page on the first display (deep-linking, e.g. a “watch from video 3” CTA), set initialPageIndex on the VideoCarouselItem instead. The declarative path lands without a horizontal scroll animation; setActiveIndex only operates on the active cell and produces an animated scroll.

iOS
React Native

Access the carousel API via shortKit.carousel. Methods are safe to call from any thread; they hop to the main queue internally.

import ShortKitSDK

shortKit.carousel.next()              // returns Bool
shortKit.carousel.previous()          // returns Bool
shortKit.carousel.setActiveIndex(2)   // returns Bool

All three methods are marked @discardableResult, so you can ignore the return value for fire-and-forget usage:

@objc private func didTapNext() {
    shortKit.carousel.next()
}

Import ShortKitCommands — the same entry point used for player commands. These methods work from inside overlay components (which run in isolated surfaces without provider context).

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

ShortKitCommands.carouselNext();              // returns boolean
ShortKitCommands.carouselPrevious();          // returns boolean
ShortKitCommands.carouselSetActiveIndex(2);   // returns boolean

Inside a React component, you can also use the useShortKitCarousel() hook — it exposes the same three methods alongside reactive state.

Return value

Result	Meaning
`true`	The carousel accepted the command. Visual transition and playback handoff are in flight.
`false`	Either no video carousel is currently active (the current feed item is a video, survey, ad, or image carousel), or the target index is out of range (`previous()` at index `0`, `next()` at the last index, or `setActiveIndex(_:)` outside `0..<videos.count`).

setActiveIndex(_:) with the current index returns true as a no-op.

Observing active state

Subscribe to reactive state to keep overlay UI, badges, or host-app chrome in sync with the active carousel.

iOS
React Native

ShortKit exposes Combine publishers on shortKit.carousel. Always dispatch to the main queue with .receive(on: DispatchQueue.main) before updating UI.

Publisher	Type	Description
`activeIndex`	`AnyPublisher<Int?, Never>`	Zero-based index of the playing video. Emits `nil` when no video carousel is active. Duplicates are filtered.
`activeCarouselChanged`	`AnyPublisher<VideoCarouselItem?, Never>`	The active carousel item. Emits `nil` when no video carousel is active. Duplicates are filtered.

Example:

import Combine

var cancellables = Set<AnyCancellable>()

shortKit.carousel.activeIndex
    .receive(on: DispatchQueue.main)
    .sink { index in
        guard let index = index else {
            pageIndicator.isHidden = true
            return
        }
        pageIndicator.isHidden = false
        pageIndicator.currentPage = index
    }
    .store(in: &cancellables)

For one-off synchronous reads, use:

Accessor	Type	Description
`activeIndexValue`	`Int?`	Current active index, or `nil`.
`videoCountValue`	`Int?`	Number of videos in the active carousel, or `nil`.
`activeCarouselItemValue`	`VideoCarouselItem?`	The active carousel item, or `nil`.

if let index = shortKit.carousel.activeIndexValue,
   let count = shortKit.carousel.videoCountValue {
    print("Playing video \(index + 1) of \(count)")
}

`useShortKitCarousel()`

A React hook that exposes reactive carousel state plus the three imperative methods. It subscribes to native events directly, so it works inside overlay components without a <ShortKitProvider> in the tree.

import { useShortKitCarousel } from '@shortkitsdk/react-native';

function PageIndicator() {
  const { activeIndex, videoCount } = useShortKitCarousel();
  if (activeIndex == null) return null;
  return <Text>{`${activeIndex + 1} / ${videoCount}`}</Text>;
}

Return value:

interface ShortKitCarouselState {
  activeIndex: number | null;         // null when no carousel is active
  videoCount: number;                 // 0 when no carousel is active
  activeCarouselItem: VideoCarouselItem | null;
  next: () => boolean;
  previous: () => boolean;
  setActiveIndex: (index: number) => boolean;
}

The component re-renders when the active carousel changes (vertical swipe onto/off of a video carousel) or when the active video index changes inside the current carousel (horizontal swipe or imperative call).

Cell gesture events

Two events fire on direct user interaction with a video-carousel cell:

onVideoCarouselCellTap — a discrete tap that didn’t turn into a horizontal pan.
onVideoCarouselCellLongPress — the lifecycle of a sustained press.

Both are passive observers on the cell. They run alongside the carousel’s horizontal pan and the feed’s vertical pan without intercepting either, so a press that becomes a horizontal swipe still pages the carousel, and a press that becomes a vertical swipe still advances the feed. Use these for analytics, custom interactions like double-tap-to-like, or hold-to-pause UX.

Tap

Fires once per discrete tap on a carousel cell that did not trigger the inner horizontal pan. Quick taps qualify; presses that turn into pans do not.

iOS
React Native

Set the closure on your ShortKitFeedViewController instance.

feedVC.onVideoCarouselCellTap = { [weak self] payload in
    analytics.track("carousel_cell_tap", [
        "carousel_id": payload.id,
        "page_index": payload.pageIndex,
    ])
}

public struct VideoCarouselCellTapPayload {
    public let id: String       // VideoCarouselItem.id
    public let index: Int       // Zero-based position of the carousel cell in the feed (its IndexPath.item)
    public let pageIndex: Int   // Inner page visible at tap time
}

Pass the prop to <ShortKitFeed>.

<ShortKitFeed
  onVideoCarouselCellTap={(event) => {
    analytics.track('carousel_cell_tap', {
      carousel_id: event.id,
      page_index: event.pageIndex,
    });
  }}
  /* ... */
/>

interface VideoCarouselCellTapEvent {
  id: string;          // VideoCarouselItem.id
  index: number;       // Zero-based position of the carousel cell in the feed
  pageIndex: number;   // Inner page visible at tap time
}

Long press

Available since SDK 0.2.36.

Fires across the lifecycle of a sustained press: a began after 0.2s of continuous touch within 10 points of the touch origin, then exactly one terminal state — ended on touch release, or cancelled if the press is interrupted.

iOS
React Native

feedVC.onVideoCarouselCellLongPress = { [weak self] payload in
    switch payload.state {
    case .began:
        self?.shortKit.player.pause()
    case .ended, .cancelled:
        self?.shortKit.player.play()
    }
}

public struct VideoCarouselCellLongPressPayload {
    public let id: String                                  // VideoCarouselItem.id
    public let index: Int                                  // Zero-based position of the carousel cell in the feed
    public let pageIndex: Int                              // Inner page visible when this lifecycle event fired
    public let state: VideoCarouselCellLongPressState
}

public enum VideoCarouselCellLongPressState: String {
    case began, ended, cancelled
}

<ShortKitFeed
  onVideoCarouselCellLongPress={(event) => {
    if (event.state === 'began') {
      ShortKitCommands.pause();
    } else {
      ShortKitCommands.play();
    }
  }}
  /* ... */
/>

interface VideoCarouselCellLongPressEvent {
  id: string;                                       // VideoCarouselItem.id
  index: number;                                    // Zero-based position of the carousel cell in the feed
  pageIndex: number;                                // Inner page visible when this lifecycle event fired
  state: 'began' | 'ended' | 'cancelled';
}

Lifecycle states

State	When it fires
`began`	After 0.2s of continuous touch within 10 points of the touch origin.
`ended`	When the user releases the touch with the recognizer still active.
`cancelled`	When the press is interrupted — by movement past 10 points, by the user starting a horizontal carousel pan or vertical feed scroll, or by the cell scrolling off-screen.

Every press that reaches began is followed by exactly one terminal state — ended or cancelled. Touches that don’t satisfy the recognizer (released before 0.2s, or moved >10 points before 0.2s) never fire any long-press event. Use state === 'began' to start an effect (pause, dim, show menu) and treat both ended and cancelled as the signal to undo it.

Recipe: hold-to-pause

A common use is letting the user pause playback by holding the cell — a familiar pattern in short-video feeds.

iOS
React Native

feedVC.onVideoCarouselCellLongPress = { [weak self] payload in
    guard let self else { return }
    switch payload.state {
    case .began:
        self.shortKit.player.pause()
    case .ended, .cancelled:
        self.shortKit.player.play()
    }
}

<ShortKitFeed
  onVideoCarouselCellLongPress={(event) => {
    if (event.state === 'began') {
      ShortKitCommands.pause();
    } else if (event.state === 'ended' || event.state === 'cancelled') {
      ShortKitCommands.play();
    }
  }}
  /* ... */
/>

Because the recognizer is a passive observer, a hold that turns into a horizontal swipe still pages the carousel — the cancelled arm of the switch is what restores playback when that happens.

This minimal recipe will resume playback after a hold even if the user had manually paused the video before holding. To preserve manual pauses, track the player state and only call play() from the ended/cancelled arm if the video was playing before began fired.

Completion events

A completion event fires each time a carousel video reaches its natural end — after playback, not on skip. Use it for analytics, end-of-carousel CTAs, or host-level auto-advance behavior that extends what the SDK does by default.

iOS
React Native

Subscribe to the activeVideoCompleted publisher on shortKit.carousel. It emits a CarouselCompletionEvent per natural end.

import Combine
import ShortKitSDK

shortKit.carousel.activeVideoCompleted
    .receive(on: DispatchQueue.main)
    .sink { event in
        analytics.track("carousel_video_completed", [
            "carousel_id": event.carouselItem.id,
            "video_id": event.contentItem.id,
            "index": event.indexInCarousel,
            "was_last": event.wasLast,
        ])
    }
    .store(in: &cancellables)

CarouselCompletionEvent

public struct CarouselCompletionEvent: Equatable, Sendable {
    public let contentItem: ContentItem
    public let indexInCarousel: Int
    public let carouselItem: VideoCarouselItem
    public let wasLast: Bool
    public let willAutoAdvance: Bool
}

Pass an onCarouselActiveVideoCompleted callback to <ShortKitFeed>. The callback receives a typed event object.

import { ShortKitFeed } from '@shortkitsdk/react-native';

<ShortKitFeed
  onCarouselActiveVideoCompleted={(event) => {
    analytics.track('carousel_video_completed', {
      carousel_id: event.carouselItem.id,
      video_id: event.contentItem.id,
      index: event.indexInCarousel,
      was_last: event.wasLast,
    });
  }}
  /* ... */
/>

Event shape

interface CarouselActiveVideoCompletedEvent {
  surfaceId: string;
  contentItem: ContentItem;
  indexInCarousel: number;
  carouselItem: VideoCarouselItem;
  wasLast: boolean;
  willAutoAdvance: boolean;
}

Event field reference

Field	Type	Description
`contentItem`	`ContentItem`	The video that just completed. Same shape as any feed `ContentItem`.
`indexInCarousel`	`Int`	Zero-based index of `contentItem` within `carouselItem.videos`.
`carouselItem`	`VideoCarouselItem`	The carousel that owns the completed video.
`wasLast`	`Bool`	`true` when the completed video was the last one in `carouselItem.videos`.
`willAutoAdvance`	`Bool`	`true` when the SDK will auto-advance to the next video after this event. Equivalent to `!wasLast` — provided explicitly so downstream logic doesn’t have to restate the rule.
`surfaceId` (React Native only)	`string`	Identifier for the feed surface that produced the event. Only meaningful when an app mounts multiple `<ShortKitFeed>` instances simultaneously; use it to route the event to the correct feed’s state.

The event fires only on natural end-of-playback. It does not fire when:

The user swipes to a different video in the carousel.
Your code calls next(), previous(), or setActiveIndex(_:).
The feed navigates vertically (by swipe or programmatically) to a different feed item.

Recipe: end-of-carousel CTA

A common use case is showing a “Read the full article” or “Subscribe” card after the user has watched every video in a carousel. Because the last video loops by default (rather than spilling into the next feed item), your host app is in full control of what happens next.

iOS
React Native

shortKit.carousel.activeVideoCompleted
    .receive(on: DispatchQueue.main)
    .sink { [weak self] event in
        guard event.wasLast, !event.willAutoAdvance else { return }
        self?.showEndOfCarouselCTA(for: event.carouselItem)
    }
    .store(in: &cancellables)

<ShortKitFeed
  onCarouselActiveVideoCompleted={(event) => {
    if (event.wasLast && !event.willAutoAdvance) {
      setEndOfCarouselCTA(event.carouselItem);
    }
  }}
/>

The wasLast && !willAutoAdvance check is the idiomatic “user reached the end of the carousel” signal. Because the video keeps looping silently underneath, you can display the CTA without worrying about playback changing out from under you — the user is either watching the last video loop or is about to swipe away.

Overlays › Video carousel overlays — render chrome on top of the native pager
Content Types › Video carousel — VideoCarouselItem data shape
Feed — the container that hosts carousels alongside videos, surveys, and ads
Player — single-video playback control (the non-carousel analog)

Get Started

Content

Display

Build Your Experience

Users & Data

Default behavior

Programmatic navigation

Return value

Observing active state

`useShortKitCarousel()`

Cell gesture events

Tap

Long press

Lifecycle states

Recipe: hold-to-pause

Completion events

CarouselCompletionEvent

Event shape

Event field reference

Recipe: end-of-carousel CTA

​Default behavior

​Programmatic navigation

​Return value

​Observing active state

​useShortKitCarousel()

​Cell gesture events

​Tap

​Long press

​Lifecycle states

​Recipe: hold-to-pause

​Completion events

​CarouselCompletionEvent

​Event shape

​Event field reference

​Recipe: end-of-carousel CTA

​Related

Default behavior

Programmatic navigation

Return value

Observing active state

`useShortKitCarousel()`

Cell gesture events

Tap

Long press

Lifecycle states

Recipe: hold-to-pause

Completion events

CarouselCompletionEvent

Event shape

Event field reference

Recipe: end-of-carousel CTA

Related