Overlays

Overlays are full-screen views layered on top of the video player in each feed cell. They read state from ShortKitPlayer reactive streams and issue commands back to the player. The SDK manages the overlay lifecycle — creating instances per cell, configuring them with content, and coordinating transitions as the user swipes between videos.

Video overlay modes

VideoOverlayMode controls what UI the SDK renders on top of video content. Set it via FeedConfig:

Swift
Kotlin
Flutter
React Native

// Custom UIKit overlay -- you provide the UI, SDK manages the lifecycle
let config = FeedConfig(videoOverlay: .custom {
    MyOverlay(theme: .dark)
})

// SwiftUI overlay -- use @ViewBuilder with player and cell content
let config = FeedConfig(videoOverlay: .swiftUI { player, cellContent in
    MySwiftUIOverlay(player: player, cellContent: cellContent)
})

// No overlay -- bare video, no UI
let config = FeedConfig(videoOverlay: .none)

// Custom overlay
val config = FeedConfig(videoOverlay = VideoOverlayMode.Custom {
    MyOverlay(theme = Theme.Dark)
})

// No overlay
val config = FeedConfig(videoOverlay = VideoOverlayMode.None)

// Custom overlay — registered by name, rendered in a separate Flutter engine
final config = FeedConfig(overlay: OverlayConfigCustom('news'));

// No overlay — bare video, no UI
final config = FeedConfig(overlay: OverlayConfigNone());

Flutter overlays run in a separate Dart isolate. Register them in a dedicated entry point using ShortKitOverlayEngine.initialize(). See Registering your overlay below.

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

// Custom overlay -- pass a React component that uses useShortKitPlayer()
<ShortKitProvider config={{ overlay: { type: "custom", component: MyOverlay } }}>
  <ShortKitFeed />
</ShortKitProvider>

// No overlay
<ShortKitProvider config={{ overlay: "none" }}>
  <ShortKitFeed />
</ShortKitProvider>

React Native uses overlay (not videoOverlay) in the FeedConfig.

Mode	Behavior
`.custom { ... }`	Provide a UIKit `UIView` conforming to `FeedOverlay`. SDK creates your overlay per cell and manages its lifecycle.
`.swiftUI { player, cellContent in ... }`	(iOS only) Provide a SwiftUI `View` via `@ViewBuilder`. Receives a `ShortKitPlayer` and a `CellContent` (an `ObservableObject` with a `@Published item: ContentItem?`). The SDK wraps it in a hosting view and manages the lifecycle.
`.none`	SDK renders only the raw video. No overlay, no controls.

Custom video overlays

When the built-in template doesn’t fit your product — custom controls, branded UI, domain-specific actions — use .custom to provide your own overlay. The SDK manages per-cell creation, content binding, and transition lifecycle exactly as it does for built-in templates. You own the UI; the SDK owns the lifecycle.

The FeedOverlay protocol

Custom overlays must conform to FeedOverlay. The SDK calls these methods at specific moments in the cell lifecycle:

Swift
Kotlin
Flutter

public protocol FeedOverlay: AnyObject {
    func attach(player: ShortKitPlayer)
    func configure(with item: ContentItem)
    func resetPlaybackProgress()
    func activatePlayback()
}

interface FeedOverlay {
    fun attach(player: ShortKitPlayer)
    fun configure(item: ContentItem)
    fun resetPlaybackProgress()
    fun activatePlayback()
}

Flutter overlays do not conform to a protocol. Instead, you register a builder function that receives the content item and current state:

typedef ShortKitOverlayBuilder = Widget Function(
  BuildContext context,
  ContentItem item,
  OverlayState state,
);

The SDK manages per-cell creation, content binding, and transition lifecycle. Your builder is called with the current ContentItem and an OverlayState snapshot. The builder re-runs whenever any field on OverlayState changes.

Field	Type	Description
`playerState`	`PlayerState`	Current playback state (`idle`, `loading`, `ready`, `playing`, `paused`, `seeking`, `buffering`, `ended`, `error`).
`time`	`PlayerTime`	`current`, `duration`, `buffered` in seconds.
`isMuted`	`bool`	Current mute state.
`playbackRate`	`double`	Current playback speed.
`captionsEnabled`	`bool`	Whether captions are on.
`activeCaptionTrack`	`CaptionTrack?`	The selected caption track, or `null`.
`activeCue`	`VTTCue?`	The active caption cue at the current time, or `null` between cues.
`feedScrollPhase`	`FeedScrollPhase`	Current feed scroll state (`dragging(from:)` or `settled`).
`isActive`	`bool`	Whether this cell is the active playback cell.

Method	When the SDK calls it	What your overlay should do
`attach(player:)`	Once, immediately after creation.	Store the player reference and subscribe to its reactive streams (`time`, `playerState`, `isMuted`, `activeCue`, etc.).
`configure(with:)`	A cell receives a new content item (initial load or cell reuse).	Update labels, thumbnails, and metadata to reflect the new item.
`resetPlaybackProgress()`	The cell is being prepared for new content.	Reset scrubber position, clear caption text, discard stale state from the previous item.
`activatePlayback()`	The cell becomes the active playback cell.	Begin processing `player.time` updates to drive your scrubber, captions, and time-dependent UI.

The SDK calls your factory closure once per cell, lazily on first use. Your overlay is added as a full-screen subview of the cell and persists across cell reuses. Immediately after creation, the SDK calls attach(player:) with its ShortKitPlayer instance — this is where you store the player reference and subscribe to its reactive streams. From that point on, the SDK drives your overlay through the remaining protocol methods. When a cell is reused for new content, it calls configure(with:) followed by resetPlaybackProgress() so your overlay can update its metadata and clear stale state. When the cell becomes the active playback cell, it calls activatePlayback() — your signal to start processing time updates.

Registering your overlay

Pass a factory closure to .custom. The closure returns a view conforming to FeedOverlay. The SDK calls attach(player:) immediately after to provide the player:

Swift
Kotlin
Flutter
React Native

let config = FeedConfig(videoOverlay: .custom {
    MyOverlay(theme: .dark, analytics: myTracker)
})

let shortKit = ShortKit(apiKey: "pk_live_...", config: config)

val config = FeedConfig(videoOverlay = VideoOverlayMode.Custom {
    MyOverlay(context, theme = Theme.Dark, analytics = myTracker)
})

val shortKit = ShortKit(apiKey = "pk_live_...", config = config)

In Flutter, overlays run in a separate Dart isolate (engine). Create a dedicated entry point and register your builders with ShortKitOverlayEngine.initialize():

overlay_main.dart

import 'package:flutter/material.dart';
import 'package:shortkit_flutter/shortkit_flutter.dart';

@pragma('vm:entry-point')
void shortKitOverlayMain() {
  ShortKitOverlayEngine.initialize(
    overlays: {
      'news': (context, item, state) => NewsOverlay(item: item, state: state),
    },
    loadingWidget: (context) => const Center(
      child: CircularProgressIndicator(),
    ),
  );
}

Reference the overlay name in your FeedConfig:

ShortKitFeed(
  config: FeedConfig(
    overlay: OverlayConfigCustom('news'),
  ),
)

Flutter currently supports only video overlays. Carousel and video-carousel overlay support is coming soon.

Use ShortKitOverlayCommands.of(context) inside your overlay widget to issue player commands:

final commands = ShortKitOverlayCommands.of(context);
commands.play();
commands.pause();
commands.seek(15.0);
commands.setMuted(false);

In React Native, custom overlays are plain React components. The SDK renders your component inside each feed cell. Use the useShortKitPlayer() hook to access player state and commands — no protocol conformance is needed.

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

<ShortKitProvider
  apiKey="pk_live_..."
  config={{ videoOverlay: { mode: "custom", component: MyOverlay } }}
>
  <ShortKitFeed />
</ShortKitProvider>

The factory is your opportunity to inject your own dependencies — themes, data services, feature flags — at construction time. On iOS and Android, the SDK provides its dependency (the player) separately through attach(player:). In React Native, your component accesses the player via the useShortKitPlayer() hook.

SwiftUI overlays

If your iOS app uses SwiftUI, use .swiftUI instead of .custom to build your overlay as a SwiftUI View. The closure receives a ShortKitPlayer and a CellContent object:

let config = FeedConfig(videoOverlay: .swiftUI { player, cellContent in
    MyOverlayView(player: player, cellContent: cellContent)
})

CellContent is an ObservableObject with a single @Published item: ContentItem? property. The SDK updates it automatically as cells are reused. Use it in your SwiftUI view to reactively display content metadata:

import SwiftUI
import ShortKitSDK

struct MyOverlayView: View {
    let player: ShortKitPlayer
    @ObservedObject var cellContent: CellContent

    var body: some View {
        VStack {
            Spacer()
            if let item = cellContent.item {
                Text(item.title)
                    .font(.headline)
                    .foregroundColor(.white)
            }
        }
        .padding()
    }
}

Under the hood, .swiftUI wraps your view in a UIHostingController and registers it as a FeedOverlay. You do not need to conform to the FeedOverlay protocol yourself.

ShortKitPlayer

ShortKitPlayer is the public interface to the video player. Both built-in templates and custom overlays use it the same way: subscribe to reactive streams for state, call methods for commands. Access it via shortKit.player.

Reactive streams

Subscribe to these streams to keep your overlay in sync with playback state. Updates are delivered on the main thread.

Publisher	Type	Description
`time`	`PlayerTime`	Elapsed time, total duration, and buffered duration. Fires at ~10 Hz while playing.
`playerState`	`PlayerState`	State transitions: `.idle`, `.loading`, `.ready`, `.playing`, `.paused`, `.seeking`, `.buffering`, `.ended`, `.error(String)`.
`currentItem`	`ContentItem?`	Metadata for the active content item. `nil` when nothing is loaded.
`isMuted`	`Bool`	Current mute state.
`playbackRate`	`Float`	Current playback speed (1.0, 1.5, 2.0).
`captionsEnabled`	`Bool`	Whether captions are currently on.
`activeCaptionTrack`	`CaptionTrack?`	The selected caption track (language, label, source).
`activeCue`	`VTTCue?`	The active caption cue at the current playback time. Contains `startTime`, `endTime`, and `text`.
`didLoop`	`LoopEvent`	Fires each time the video loops. Contains `contentId` and `loopCount`.
`feedTransition`	`FeedTransitionEvent`	Start and end of feed navigation. Contains `phase` (`.began`/`.ended`), `from`, `to`, `direction`.
`feedScrollPhase`	`FeedScrollPhase`	Current scroll state: `.dragging(from: contentId)` or `.settled`.
`feedReady`	`Void`	Fires once when the feed has loaded and assigned the first player.

Synchronous reads are available without subscribing via currentItemValue and playbackRateValue.

Commands

Call these methods from your gesture handlers and buttons to control playback:

Method	Description
`play()`	Resume playback.
`pause()`	Pause playback.
`seek(to:)`	Seek to a time in seconds. Does not auto-resume.
`seekAndPlay(to:)`	Seek to a time and immediately resume playback.
`setMuted(_:)`	Set mute state.
`skipToNext()`	Navigate to the next feed item.
`skipToPrevious()`	Navigate to the previous feed item.
`setPlaybackRate(_:)`	Set playback speed (e.g. 1.0, 1.5, 2.0).
`setCaptionsEnabled(_:)`	Enable or disable captions.
`selectCaptionTrack(language:)`	Select a caption track by BCP 47 language code (e.g. “en”).
`sendContentSignal(_:)`	Send a `.positive` or `.negative` signal for the recommendation engine. Call this when a user likes, shares, or otherwise engages with content.
`setMaxBitrate(_:)`	Cap video bitrate in bits per second. Pass 0 to uncap.
`seekThumbnail(at:)`	Returns a thumbnail image at the given time for scrubber preview, or `nil` if unavailable.

ContentItem

The content metadata available to your overlay via configure(with:) and the currentItem publisher:

Field	Type	Description
`id`	`String`	Unique content identifier.
`title`	`String`	Content title.
`description`	`String?`	Content description.
`duration`	`Double`	Total duration in seconds.
`streamingUrl`	`String`	HLS streaming URL.
`thumbnailUrl`	`String`	Poster image URL.
`captionTracks`	`[CaptionTrack]`	Available caption tracks.
`customMetadata`	`[String: JSONValue]?`	App-specific metadata attached to the content.
`author`	`String?`	Content author.
`articleUrl`	`String?`	Link to the full article.
`commentCount`	`Int?`	Number of comments.

Example: scrubber with seek thumbnails

This example shows a draggable scrubber that displays a thumbnail preview at the seek position while the user drags. It uses player.time to track progress and player.seekThumbnail(at:) to fetch storyboard frames.

Swift
Kotlin
Flutter
React Native
Web

import Combine
import ShortKit
import UIKit

final class ScrubberOverlay: UIView, FeedOverlay {

    private var player: ShortKitPlayer!
    private var subscriptions = Set<AnyCancellable>()
    private var isActive = false
    private var isScrubbing = false
    private var videoDuration: Double = 0

    // MARK: - UI

    private let track = UIView()
    private let playedProgress = UIView()
    private let bufferedProgress = UIView()
    private let thumbnailPreview = UIImageView()
    private let timeLabel = UILabel()

    private var playedWidth: NSLayoutConstraint!
    private var bufferedWidth: NSLayoutConstraint!
    private var handleCenterX: NSLayoutConstraint!

    override init(frame: CGRect) {
        super.init(frame: frame)
        setupUI()
    }

    required init?(coder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }

    // MARK: - FeedOverlay

    func attach(player: ShortKitPlayer) {
        self.player = player
        player.time
            .receive(on: DispatchQueue.main)
            .sink { [weak self] time in
                guard let self, self.isActive, !self.isScrubbing else { return }
                self.videoDuration = time.duration
                let fraction = time.duration > 0 ? time.current / time.duration : 0
                self.playedWidth.constant = self.track.bounds.width * fraction
                let buffered = time.duration > 0 ? time.buffered / time.duration : 0
                self.bufferedWidth.constant = self.track.bounds.width * buffered
            }
            .store(in: &subscriptions)
    }

    func configure(with item: ContentItem) {
        videoDuration = item.duration
    }

    func resetPlaybackProgress() {
        isActive = false
        isScrubbing = false
        playedWidth.constant = 0
        bufferedWidth.constant = 0
        thumbnailPreview.isHidden = true
        timeLabel.isHidden = true
    }

    func activatePlayback() { isActive = true }

    // MARK: - Scrub gesture

    @objc private func handlePan(_ gesture: UIPanGestureRecognizer) {
        let x = gesture.location(in: track).x
        let fraction = max(0, min(1, x / track.bounds.width))
        let seekTime = videoDuration * fraction

        switch gesture.state {
        case .began:
            isScrubbing = true
            thumbnailPreview.isHidden = false
            timeLabel.isHidden = false

        case .changed:
            handleCenterX.constant = track.bounds.width * fraction
            playedWidth.constant = track.bounds.width * fraction

            if let thumb = player.seekThumbnail(at: seekTime) {
                thumbnailPreview.image = thumb
            }
            let m = Int(seekTime) / 60, s = Int(seekTime) % 60
            timeLabel.text = String(format: "%d:%02d", m, s)
            thumbnailPreview.center.x = handleCenterX.constant

        case .ended, .cancelled:
            isScrubbing = false
            thumbnailPreview.isHidden = true
            timeLabel.isHidden = true
            player.seekAndPlay(to: seekTime)

        default: break
        }
    }

    // MARK: - Setup (abbreviated — layout constraints omitted for brevity)

    private func setupUI() {
        track.backgroundColor = UIColor.white.withAlphaComponent(0.2)
        addSubview(track)
        track.addSubview(bufferedProgress)
        track.addSubview(playedProgress)
        addSubview(thumbnailPreview)
        addSubview(timeLabel)

        // ... constraint setup for track at bottom, progress bars, thumbnail above track

        let pan = UIPanGestureRecognizer(target: self, action: #selector(handlePan))
        track.addGestureRecognizer(pan)
    }
}

class ScrubberOverlay @JvmOverloads constructor(
    context: Context,
    attrs: AttributeSet? = null
) : FrameLayout(context, attrs), FeedOverlay {

    private lateinit var player: ShortKitPlayer
    private var isActive = false
    private var isScrubbing = false
    private var videoDuration = 0.0

    private val track: View
    private val playedProgress: View
    private val bufferedProgress: View
    private val thumbnailPreview: ImageView
    private val timeLabel: TextView

    init {
        inflate(context, R.layout.scrubber_overlay, this)
        track = findViewById(R.id.track)
        playedProgress = findViewById(R.id.playedProgress)
        bufferedProgress = findViewById(R.id.bufferedProgress)
        thumbnailPreview = findViewById(R.id.thumbnailPreview)
        timeLabel = findViewById(R.id.timeLabel)

        track.setOnTouchListener { _, event -> handleTouch(event) }
    }

    // FeedOverlay

    override fun attach(player: ShortKitPlayer) {
        this.player = player
        findViewTreeLifecycleOwner()?.lifecycleScope?.launch {
            player.time.collect { time ->
                if (!isActive || isScrubbing) return@collect
                videoDuration = time.duration
                val fraction = if (time.duration > 0) time.current / time.duration else 0.0
                playedProgress.layoutParams.width = (track.width * fraction).toInt()
                playedProgress.requestLayout()
                val buffered = if (time.duration > 0) time.buffered / time.duration else 0.0
                bufferedProgress.layoutParams.width = (track.width * buffered).toInt()
                bufferedProgress.requestLayout()
            }
        }
    }

    override fun configure(item: ContentItem) {
        videoDuration = item.duration
    }

    override fun resetPlaybackProgress() {
        isActive = false
        isScrubbing = false
        playedProgress.layoutParams.width = 0
        bufferedProgress.layoutParams.width = 0
        thumbnailPreview.visibility = View.GONE
        timeLabel.visibility = View.GONE
    }

    override fun activatePlayback() { isActive = true }

    private fun handleTouch(event: MotionEvent): Boolean {
        val fraction = (event.x / track.width).coerceIn(0f, 1f).toDouble()
        val seekTime = videoDuration * fraction

        when (event.action) {
            MotionEvent.ACTION_DOWN -> {
                isScrubbing = true
                thumbnailPreview.visibility = View.VISIBLE
                timeLabel.visibility = View.VISIBLE
            }
            MotionEvent.ACTION_MOVE -> {
                playedProgress.layoutParams.width = (track.width * fraction).toInt()
                playedProgress.requestLayout()

                player.seekThumbnail(seekTime)?.let { thumbnailPreview.setImageBitmap(it) }

                val m = (seekTime / 60).toInt()
                val s = (seekTime % 60).toInt()
                timeLabel.text = String.format("%d:%02d", m, s)
                thumbnailPreview.x = (track.width * fraction).toFloat() - thumbnailPreview.width / 2
            }
            MotionEvent.ACTION_UP, MotionEvent.ACTION_CANCEL -> {
                isScrubbing = false
                thumbnailPreview.visibility = View.GONE
                timeLabel.visibility = View.GONE
                player.seekAndPlay(seekTime)
            }
        }
        return true
    }
}

Widget scrubberOverlay(BuildContext context, ContentItem item, OverlayState state) {
  final commands = ShortKitOverlayCommands.of(context);
  final progress = state.time.duration > 0
      ? state.time.current / state.time.duration
      : 0.0;
  final buffered = state.time.duration > 0
      ? state.time.buffered / state.time.duration
      : 0.0;

  return Stack(
    children: [
      // Progress track at bottom
      Positioned(
        left: 0,
        right: 0,
        bottom: 44,
        child: GestureDetector(
          onHorizontalDragUpdate: (details) {
            final box = context.findRenderObject() as RenderBox;
            final fraction = (details.localPosition.dx / box.size.width)
                .clamp(0.0, 1.0);
            final seekTime = item.duration * fraction;
            commands.seekAndPlay(seekTime);
          },
          child: SizedBox(
            height: 3,
            child: Stack(
              children: [
                Container(color: Colors.white24),
                FractionallySizedBox(
                  widthFactor: buffered,
                  child: Container(color: Colors.white30),
                ),
                FractionallySizedBox(
                  widthFactor: progress,
                  child: Container(color: Colors.white),
                ),
              ],
            ),
          ),
        ),
      ),
    ],
  );
}

import { useRef, useState } from "react";
import { View, Image, Text, StyleSheet } from "react-native";
import { Gesture, GestureDetector } from "react-native-gesture-handler";
import { useShortKitPlayer, ShortKitCommands } from "@shortkitsdk/react-native";

export function ScrubberOverlay() {
  const {
    time, currentItem, isActive, isTransitioning,
    seekAndPlay,
  } = useShortKitPlayer();

  const [isScrubbing, setIsScrubbing] = useState(false);
  const [seekFraction, setSeekFraction] = useState(0);
  const trackRef = useRef(null);

  const progress = (!isScrubbing && isActive && time.duration > 0)
    ? time.current / time.duration
    : seekFraction;

  const buffered = time.duration > 0
    ? time.buffered / time.duration
    : 0;

  const panGesture = Gesture.Pan()
    .onBegin(() => {
      setIsScrubbing(true);
      // Give this drag exclusive priority over the feed's vertical swipe.
      ShortKitCommands.setFeedScrollEnabled(false);
    })
    .onUpdate((e) => {
      trackRef.current?.measure((_x, _y, width) => {
        const frac = Math.max(0, Math.min(1, e.x / width));
        setSeekFraction(frac);
      });
    })
    .onEnd(() => {
      const seekTime = (currentItem?.duration ?? 0) * seekFraction;
      seekAndPlay(seekTime);
      setIsScrubbing(false);
    })
    .onFinalize(() => {
      // Restore feed swipe on release or cancellation.
      ShortKitCommands.setFeedScrollEnabled(true);
    });

  const seekTime = (currentItem?.duration ?? 0) * seekFraction;
  const minutes = Math.floor(seekTime / 60);
  const seconds = Math.floor(seekTime % 60);

  return (
    <View style={[styles.overlay, isTransitioning && styles.dimmed]}>
      {isScrubbing && (
        <View style={[styles.preview, { left: `${seekFraction * 100}%` }]}>
          <Text style={styles.time}>{`${minutes}:${String(seconds).padStart(2, "0")}`}</Text>
        </View>
      )}
      <GestureDetector gesture={panGesture}>
        <View ref={trackRef} style={styles.track}>
          <View style={[styles.buffered, { width: `${buffered * 100}%` }]} />
          <View style={[styles.played, { width: `${progress * 100}%` }]} />
        </View>
      </GestureDetector>
    </View>
  );
}

const styles = StyleSheet.create({
  overlay: { ...StyleSheet.absoluteFillObject, justifyContent: "flex-end" },
  dimmed: { opacity: 0.3 },
  track: { height: 3, backgroundColor: "rgba(255,255,255,0.2)", marginBottom: 44 },
  played: { height: 3, backgroundColor: "#fff", position: "absolute" },
  buffered: { height: 3, backgroundColor: "rgba(255,255,255,0.3)", position: "absolute" },
  preview: { position: "absolute", bottom: 60, alignItems: "center", marginLeft: -60 },
  time: { color: "#fff", fontSize: 12, fontVariant: ["tabular-nums"], marginTop: 4 },
});

const sk = new ShortKit({ apiKey: 'pk_live_...' });
sk.createFeed(document.getElementById('feed'), {
  config: {
    overlay: (container, { item, player, feed }) => {
      // Build scrubber UI
      const scrubber = document.createElement('div');
      scrubber.style.cssText = 'position:absolute;bottom:0;left:0;right:0;height:4px;background:rgba(255,255,255,0.3);';
      const progress = document.createElement('div');
      progress.style.cssText = 'height:100%;background:#fff;width:0%;';
      scrubber.appendChild(progress);
      container.appendChild(scrubber);

      player.on('timeUpdate', ({ current, duration }) => {
        if (duration > 0) progress.style.width = `${(current / duration) * 100}%`;
      });
    },
  },
});

The key pattern: guard on isActive and !isScrubbing in your time stream handler so you only update the scrubber from playback when the overlay is active and the user isn’t dragging. During a drag, update the UI from the gesture position instead and call player.seekAndPlay(to:) on release.

Feed scroll control

By default the feed owns vertical swipe: dragging up or down navigates between items. When a custom overlay has its own drag gesture — a horizontal scrubber, a slider, a draggable control — the feed’s swipe can capture the touch mid-drag. Toggle feed scroll to give your gesture exclusive priority while it is in flight: disable it when the gesture starts, re-enable it when the gesture ends or is cancelled.

Swift
Kotlin
Flutter
React Native
Web

Call it on the player:

shortKit.player.setFeedScrollEnabled(false) // block vertical feed swipe
shortKit.player.setFeedScrollEnabled(true)  // restore vertical feed swipe

Call it on your feed fragment:

feedFragment.setFeedScrollEnabled(false) // block vertical feed swipe
feedFragment.setFeedScrollEnabled(true)  // restore vertical feed swipe

Call it through ShortKitCommands:

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

ShortKitCommands.setFeedScrollEnabled(false); // block vertical feed swipe
ShortKitCommands.setFeedScrollEnabled(true);  // restore vertical feed swipe

The scrubber example above wires this in: onBegin disables scroll and onFinalize restores it, so the feed is always re-enabled even if the drag is cancelled.

Call it as a matched pair driven by your gesture lifecycle: disable when the gesture starts, re-enable when it ends or is cancelled.

This is a transient handoff for an in-flight gesture, not a persistent feed lock. The toggle stays where you set it: if you disable scroll and never re-enable it, vertical swipe stays blocked. Always pair a disable call with a matching re-enable.

Example: closed captions

This example shows a caption label that follows the active cue and can be repositioned by dragging. It uses player.activeCue for the text and a pan gesture for repositioning.

Swift
Kotlin
Flutter
React Native
Web

import Combine
import ShortKit
import UIKit

final class CaptionOverlay: UIView, FeedOverlay {

    private var player: ShortKitPlayer!
    private var subscriptions = Set<AnyCancellable>()
    private var isActive = false
    private var captionBottomOffset: NSLayoutConstraint!

    private let captionLabel: UILabel = {
        let label = UILabel()
        label.numberOfLines = 0
        label.textAlignment = .center
        label.textColor = .white
        label.font = .systemFont(ofSize: 16, weight: .semibold)
        label.backgroundColor = UIColor.black.withAlphaComponent(0.6)
        label.layer.cornerRadius = 6
        label.clipsToBounds = true
        label.isUserInteractionEnabled = true
        label.translatesAutoresizingMaskIntoConstraints = false
        return label
    }()

    private let captionToggle = UIButton(type: .system)

    override init(frame: CGRect) {
        super.init(frame: frame)
        setupUI()
    }

    required init?(coder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }

    // MARK: - FeedOverlay

    func attach(player: ShortKitPlayer) {
        self.player = player

        player.activeCue
            .receive(on: DispatchQueue.main)
            .sink { [weak self] cue in
                guard let self, self.isActive else { return }
                if let cue {
                    self.captionLabel.text = "  \(cue.text)  "
                    self.captionLabel.isHidden = false
                } else {
                    self.captionLabel.isHidden = true
                }
            }
            .store(in: &subscriptions)

        player.captionsEnabled
            .receive(on: DispatchQueue.main)
            .sink { [weak self] enabled in
                self?.captionToggle.alpha = enabled ? 1.0 : 0.5
                if !enabled { self?.captionLabel.isHidden = true }
            }
            .store(in: &subscriptions)
    }

    func configure(with item: ContentItem) {
        captionLabel.text = nil
        captionLabel.isHidden = true
    }

    func resetPlaybackProgress() {
        isActive = false
        captionLabel.text = nil
        captionLabel.isHidden = true
        captionBottomOffset.constant = -100
    }

    func activatePlayback() { isActive = true }

    // MARK: - Drag to reposition

    @objc private func handleDrag(_ gesture: UIPanGestureRecognizer) {
        captionBottomOffset.constant += gesture.translation(in: self).y
        gesture.setTranslation(.zero, in: self)
    }

    @objc private func toggleCaptions() {
        player.captionsEnabled
            .first()
            .sink { [weak self] enabled in
                self?.player.setCaptionsEnabled(!enabled)
            }
            .store(in: &subscriptions)
    }

    private func setupUI() {
        addSubview(captionLabel)
        addSubview(captionToggle)

        captionBottomOffset = captionLabel.bottomAnchor.constraint(
            equalTo: bottomAnchor, constant: -100
        )
        NSLayoutConstraint.activate([
            captionLabel.centerXAnchor.constraint(equalTo: centerXAnchor),
            captionLabel.widthAnchor.constraint(lessThanOrEqualTo: widthAnchor, constant: -48),
            captionBottomOffset,
        ])

        captionLabel.addGestureRecognizer(
            UIPanGestureRecognizer(target: self, action: #selector(handleDrag))
        )
        captionToggle.addTarget(self, action: #selector(toggleCaptions), for: .touchUpInside)
    }
}

class CaptionOverlay @JvmOverloads constructor(
    context: Context,
    attrs: AttributeSet? = null
) : FrameLayout(context, attrs), FeedOverlay {

    private lateinit var player: ShortKitPlayer
    private var isActive = false

    private val captionLabel: TextView
    private val captionToggle: ImageButton
    private var captionOffsetY = 0f

    init {
        inflate(context, R.layout.caption_overlay, this)
        captionLabel = findViewById(R.id.captionLabel)
        captionToggle = findViewById(R.id.captionToggle)

        // Drag to reposition
        captionLabel.setOnTouchListener { view, event ->
            when (event.action) {
                MotionEvent.ACTION_MOVE -> {
                    captionOffsetY += event.y - view.height / 2
                    view.translationY = captionOffsetY
                }
            }
            true
        }

        captionToggle.setOnClickListener {
            val enabled = player.captionsEnabledValue
            player.setCaptionsEnabled(!enabled)
        }
    }

    override fun attach(player: ShortKitPlayer) {
        this.player = player
        findViewTreeLifecycleOwner()?.lifecycleScope?.apply {
            launch {
                player.activeCue.collect { cue ->
                    if (!isActive) return@collect
                    if (cue != null) {
                        captionLabel.text = cue.text
                        captionLabel.visibility = View.VISIBLE
                    } else {
                        captionLabel.visibility = View.GONE
                    }
                }
            }
            launch {
                player.captionsEnabled.collect { enabled ->
                    captionToggle.alpha = if (enabled) 1.0f else 0.5f
                    if (!enabled) captionLabel.visibility = View.GONE
                }
            }
        }
    }

    override fun configure(item: ContentItem) {
        captionLabel.text = null
        captionLabel.visibility = View.GONE
    }

    override fun resetPlaybackProgress() {
        isActive = false
        captionLabel.text = null
        captionLabel.visibility = View.GONE
        captionOffsetY = 0f
        captionLabel.translationY = 0f
    }

    override fun activatePlayback() { isActive = true }
}

Widget captionOverlay(BuildContext context, ContentItem item, OverlayState state) {
  final commands = ShortKitOverlayCommands.of(context);
  final cueText = state.activeCue?.text;

  return Stack(
    children: [
      if (state.captionsEnabled && cueText != null)
        Positioned(
          bottom: 100,
          left: 24,
          right: 24,
          child: Center(
            child: Container(
              padding: const EdgeInsets.symmetric(horizontal: 12, vertical: 6),
              decoration: BoxDecoration(
                color: Colors.black54,
                borderRadius: BorderRadius.circular(6),
              ),
              child: Text(
                cueText,
                style: const TextStyle(
                  color: Colors.white,
                  fontSize: 16,
                  fontWeight: FontWeight.w600,
                ),
                textAlign: TextAlign.center,
              ),
            ),
          ),
        ),
      Positioned(
        bottom: 60,
        right: 16,
        child: GestureDetector(
          onTap: () => commands.setCaptionsEnabled(!state.captionsEnabled),
          child: Opacity(
            opacity: state.captionsEnabled ? 1.0 : 0.5,
            child: const Text(
              'CC',
              style: TextStyle(color: Colors.white, fontSize: 16, fontWeight: FontWeight.w700),
            ),
          ),
        ),
      ),
    ],
  );
}

import { View, Text, Pressable, StyleSheet } from "react-native";
import { Gesture, GestureDetector } from "react-native-gesture-handler";
import Animated, { useSharedValue, useAnimatedStyle } from "react-native-reanimated";
import { useShortKitPlayer } from "@shortkitsdk/react-native";

export function CaptionOverlay() {
  const {
    activeCue, captionsEnabled, isActive, isTransitioning,
    setCaptionsEnabled,
  } = useShortKitPlayer();
  const offsetY = useSharedValue(0);

  const cueText = isActive ? activeCue?.text : null;

  const dragGesture = Gesture.Pan().onUpdate((e) => {
    offsetY.value += e.translationY;
  });

  const captionStyle = useAnimatedStyle(() => ({
    transform: [{ translateY: offsetY.value }],
  }));

  return (
    <View style={[styles.overlay, isTransitioning && styles.dimmed]}>
      {cueText && captionsEnabled && (
        <GestureDetector gesture={dragGesture}>
          <Animated.View style={[styles.captionBox, captionStyle]}>
            <Text style={styles.captionText}>{cueText}</Text>
          </Animated.View>
        </GestureDetector>
      )}
      <Pressable
        style={[styles.toggle, !captionsEnabled && styles.toggleOff]}
        onPress={() => setCaptionsEnabled(!captionsEnabled)}
      >
        <Text style={styles.toggleIcon}>CC</Text>
      </Pressable>
    </View>
  );
}

const styles = StyleSheet.create({
  overlay: { ...StyleSheet.absoluteFillObject },
  dimmed: { opacity: 0.3 },
  captionBox: {
    position: "absolute", bottom: 100, alignSelf: "center",
    backgroundColor: "rgba(0,0,0,0.6)", borderRadius: 6, paddingHorizontal: 12, paddingVertical: 6,
  },
  captionText: { color: "#fff", fontSize: 16, fontWeight: "600", textAlign: "center" },
  toggle: {
    position: "absolute", bottom: 60, right: 16, width: 44, height: 44,
    justifyContent: "center", alignItems: "center",
  },
  toggleOff: { opacity: 0.5 },
  toggleIcon: { color: "#fff", fontSize: 16, fontWeight: "700" },
});

const sk = new ShortKit({ apiKey: 'pk_live_...' });
sk.createFeed(document.getElementById('feed'), {
  config: {
    overlay: (container, { item, player, feed }) => {
      const cueEl = document.createElement('div');
      cueEl.style.cssText = 'position:absolute;bottom:80px;left:16px;right:16px;color:#fff;font-size:16px;text-align:center;text-shadow:0 1px 3px rgba(0,0,0,0.8);';
      container.appendChild(cueEl);

      player.on('cueChange', (cue) => {
        cueEl.textContent = cue ? cue.text : '';
      });
    },
  },
});

The activeCue publisher emits a VTTCue (with startTime, endTime, and text) when a cue becomes active, and nil when no cue covers the current playback time. The SDK handles cue timing internally — your overlay just renders whatever text it receives.

Engagement signals

When your custom overlay includes actions like likes, shares, or saves, report them to the SDK using sendContentSignal. This feeds the recommendation engine so future feed content reflects user preferences.

Swift
Kotlin
React Native

// User liked the video
player.sendContentSignal(.positive)

// User tapped "not interested"
player.sendContentSignal(.negative)

player.sendContentSignal(ContentSignal.Positive)
player.sendContentSignal(ContentSignal.Negative)

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

const { sendContentSignal } = useShortKitPlayer();
sendContentSignal("positive");
sendContentSignal("negative");

Custom overlays handle their own user interaction callbacks and report engagement through content signals.

Carousel, survey, and ad overlay modes

Image carousels, video carousels, surveys, and native ads follow the same overlay pattern as video content. Each has a mode enum with .none and .custom { ... }. The relationship is the same: the SDK owns the cell lifecycle, and the overlay provides the UI.

Swift
Kotlin
React Native

let config = FeedConfig(
    videoOverlay: .custom { MyVideoOverlay() },
    carouselOverlay: .custom { MyCarouselOverlay() },
    videoCarouselOverlay: .custom { MyVideoCarouselOverlay() },
    surveyOverlay: .custom { MySurveyOverlay() },
    adOverlay: .custom { MyAdOverlay() }
)

val config = FeedConfig(
    videoOverlay = VideoOverlayMode.Custom { MyVideoOverlay(context) },
    carouselOverlay = CarouselOverlayMode.Custom { MyCarouselOverlay(context) },
    videoCarouselOverlay = VideoCarouselOverlayMode.Custom { MyVideoCarouselOverlay(context) },
    surveyOverlay = SurveyOverlayMode.Custom { MySurveyOverlay(context) },
    adOverlay = AdOverlayMode.Custom { MyAdOverlay(context) }
)

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

<ShortKitProvider
  config={{
    overlay: { type: "custom", component: MyVideoOverlay },
    carouselOverlay: { type: "custom", component: MyCarouselOverlay },
    videoCarouselOverlay: { type: "custom", name: "myVideoCarousel", component: MyVideoCarouselOverlay },
    surveyMode: { type: "template", name: "default" },
  }}
>
  <ShortKitFeed />
</ShortKitProvider>

React Native uses overlay (not videoOverlay), surveyMode (not surveyOverlay), and does not support adOverlay. Survey overlays in React Native only support a built-in template — custom survey components are available on iOS and Android only.

Mode	Options	Behavior
`CarouselOverlayMode`	`.custom { ... }`	SDK creates your overlay per cell and manages its lifecycle. You own the entire carousel UI.
	`.none`	No carousel UI. Developer accesses raw `ImageCarouselItem` data.
`VideoCarouselOverlayMode`	`.custom { ... }`	SDK creates your overlay per cell and manages its lifecycle. The SDK handles video paging and playback natively; your overlay provides chrome (titles, buttons, page indicators) on top.
	`.none`	SDK renders the native video pager with built-in page indicators. No custom overlay.
`SurveyOverlayMode`	`.custom { ... }`	SDK creates your overlay per cell and manages its lifecycle. You own the survey UI and report responses via callbacks.
	`.none`	No survey UI. Developer accesses raw `SurveyItem` data.
`AdOverlayMode`	`.custom { ... }`	SDK creates your overlay per cell and manages its lifecycle. You own the ad UI and must handle policy compliance.
	`.none`	No ad overlay UI. Developer accesses raw `NativeAdContent` data.

Custom carousel overlays

Custom carousel overlays conform to CarouselOverlay. Unlike video overlays, there is no player — the overlay owns everything: image display, auto-scroll, text, and actions. The SDK provides carousel data through configure(with:) and manages cell lifecycle.

Swift
Kotlin

public protocol CarouselOverlay: AnyObject {
    var cachedImage: ((String) -> UIImage?)? { get set }
    func configure(with item: ImageCarouselItem)
    func resetState()
}

interface CarouselOverlay {
    var cachedImage: ((url: String) -> Bitmap?)?
    fun configure(item: ImageCarouselItem)
    fun resetState()
}

Method / Property	When the SDK calls it	What your overlay should do
`cachedImage`	Set by the SDK before calling `configure(with:)`.	Use this closure to look up prefetched images by URL, avoiding redundant downloads.
`configure(with:)`	A cell receives a new carousel item (initial load or cell reuse).	Load images, set up page indicators, populate text and metadata from the `ImageCarouselItem`.
`resetState()`	The cell is being prepared for new content.	Cancel auto-scroll timers, clear images, reset page position and any expanded text state.

The ImageCarouselItem provided in configure(with:) contains the carousel’s images, metadata, and optional auto-scroll interval. Your overlay is responsible for displaying the images and handling all user interaction — paging, text expansion, action buttons — directly.

Video carousel overlays

Video carousel overlays conform to VideoCarouselOverlay. Unlike image carousel overlays, the SDK handles horizontal video paging and playback natively — your overlay only provides the chrome layer (titles, buttons, page indicators) rendered on top.

Swift
Kotlin

public protocol VideoCarouselOverlay: AnyObject {
    func configure(with item: VideoCarouselItem)
    func updateActiveVideo(index: Int, item: ContentItem)
    func resetState()

    // Optional — default implementations provided
    func attach(player: ShortKitPlayer)
    func activatePlayback()
    func deactivatePlayback()
}

interface VideoCarouselOverlay {
    fun configure(item: VideoCarouselItem)
    fun updateActiveVideo(index: Int, item: ContentItem)
    fun resetState()

    // Optional — default no-op implementations
    fun attach(player: ShortKitPlayer) {}
    fun activatePlayback() {}
    fun deactivatePlayback() {}
}

Method	When the SDK calls it	What your overlay should do
`configure(with:)`	A cell receives a new video carousel item (initial load or cell reuse).	Populate carousel-level metadata (title, author, section) and set up page indicators for `item.videos.count` pages.
`updateActiveVideo(index:item:)`	The user swipes horizontally to a different video page.	Update the active page indicator and any per-video metadata (title, duration). The `item` parameter is the `ContentItem` for the newly active video.
`resetState()`	The cell is being prepared for new content.	Clear text, reset page indicators, cancel any pending animations.
`attach(player:)`	Once, after creation.	Store the player reference and subscribe to its reactive streams (`time`, `playerState`, `isMuted`, etc.) to display playback state in your overlay.
`activatePlayback()`	The cell becomes the active (on-screen) cell.	Begin processing player time updates to drive scrubbers, captions, etc.
`deactivatePlayback()`	The cell scrolls off-screen.	Stop processing time updates and pause any overlay animations.

In React Native, video carousel overlays are React components that receive props directly:

interface VideoCarouselOverlayProps {
  carouselItem: VideoCarouselItem;
  activeVideo: ContentItem;
  activeVideoIndex: number;
  isActive: boolean;
  time: PlayerTime;
  playerState: PlayerState;
  isMuted: boolean;
  feedId?: string; // the feed this cell belongs to — see Per-feed overlay binding
}

<ShortKitProvider
  config={{
    videoCarouselOverlay: {
      type: "custom",
      name: "myVideoCarousel",
      component: MyVideoCarouselOverlay,
    },
  }}
>
  <ShortKitFeed />
</ShortKitProvider>

Your component re-renders when the active video changes (horizontal swipe), when the cell becomes active/inactive (vertical swipe), and when player state updates. Use activeVideoIndex to render page indicators and carouselItem for carousel-level metadata. To observe or control the active carousel from your overlay or host app — navigate between videos programmatically, read the active index, or react to video completions — see Video carousel.

Per-feed overlay binding (React Native)

When you mount more than one <ShortKitFeed> at the same time — for example one feed per tab in a swipeable tab layout — each feed’s overlay cells need to know which feed they belong to, so they render that feed’s own data instead of whichever feed is currently focused. Give each mounted feed a stable, unique feedKey:

<ShortKitFeed feedKey="for-you" config={{ /* ... */ }} style={{ flex: 1 }} />
<ShortKitFeed feedKey="following" config={{ /* ... */ }} style={{ flex: 1 }} />

Every overlay component that feed renders then receives a matching feedId prop, equal to that feed’s feedKey:

function MyVideoCarouselOverlay({ feedId, carouselItem }: VideoCarouselOverlayProps) {
  // feedId === "for-you" or "following" — resolve this feed's own state with it
}

feedId is present on the props of every overlay component — video, image-carousel, and video-carousel overlays. When you don’t supply a feedKey, the SDK generates a random feed id and overlays receive that, which is all the single-feed case needs. Pass an explicit feedKey only when multiple feeds are mounted at once and overlays must be attributed to a specific feed.

At its first or last page, the video carousel releases a horizontal pan instead of consuming it, so the gesture can flow to whatever scroll container wraps the feed. This is what makes edge-swipe tab navigation possible — but it is not automatic on its own. You have to host the feed inside a swipe-enabled pager (e.g. a tab navigator with swipe gestures enabled), and whether an edge swipe actually advances a tab is determined by that pager’s own gesture handling, which you configure on the host side. The SDK’s only role is to stop the carousel from absorbing the pan at its edges.

Custom survey overlays

Custom survey overlays conform to SurveyOverlay. The protocol includes two callback properties that the SDK sets on your overlay after creation. Your overlay calls these when the user selects a survey option — the SDK handles forwarding the response to the host app delegate and triggering auto-advance.

Swift
Kotlin

public protocol SurveyOverlay: AnyObject {
    var onSurveyResponse: ((String, SurveyOption) -> Void)? { get set }
    var onAutoAdvance: (() -> Void)? { get set }
    func configure(with item: SurveyItem)
    func resetState()
}

interface SurveyOverlay {
    var onSurveyResponse: ((surveyId: String, option: SurveyOption) -> Unit)?
    var onAutoAdvance: (() -> Unit)?
    fun configure(item: SurveyItem)
    fun resetState()
}

Method	When the SDK calls it	What your overlay should do
`configure(with:)`	A cell receives a new survey item.	Display the question and option buttons from the `SurveyItem`.
`resetState()`	The cell is being prepared for new content.	Cancel any pending auto-advance timers, clear selection state, reset button styling.
`onSurveyResponse`	Set by SDK after creation.	Call this with the survey ID and selected option when the user taps an answer.
`onAutoAdvance`	Set by SDK after creation.	Call this after a short delay following selection (e.g. 500ms). The SDK scrolls to the next feed item.

Custom ad overlays

Custom ad overlays conform to AdOverlay. They apply to native ads only — ads where the video plays through ShortKit’s own PlayerPool and the SDK provides creative metadata via NativeAdContent. System-defined ads (IMA/VAST) render their own UI through the ad provider and are unaffected by this setting.

Swift
Kotlin

public protocol AdOverlay: AnyObject {
    func configure(with content: NativeAdContent)
    func resetState()
}

interface AdOverlay {
    fun configure(content: NativeAdContent)
    fun resetState()
}

Method	When the SDK calls it	What your overlay should do
`configure(with:)`	A cell receives native ad content.	Display the headline, sponsor logo, CTA button, Ad badge, and AdChoices icon from the `NativeAdContent`. Call `content.recordImpression?()` when the ad becomes visible.
`resetState()`	The cell is being prepared for new content.	Clear creative assets, reset impression state.

NativeAdContent provides all creative assets and action handlers:

Field	Type	Description
`headline`	`String?`	Ad headline text.
`body`	`String?`	Description text.
`callToAction`	`String?`	CTA label (e.g. “Learn More”, “Shop Now”).
`advertiser`	`String?`	Advertiser or sponsor name.
`sponsorIcon`	`UIImage?`	Sponsor logo.
`adChoicesIcon`	`UIImage?`	AdChoices icon from the ad SDK.
`ctaClickHandler`	`(() -> Void)?`	Call when the user taps the CTA.
`adChoicesClickHandler`	`(() -> Void)?`	Call when the user taps the AdChoices icon.
`recordImpression`	`(() -> Void)?`	Call when the ad becomes visible.

Ad policy compliance. When building a custom ad overlay, you are responsible for rendering the required policy elements: an “Ad” badge and a tappable AdChoices icon (minimum 15x15pt). Verify your implementation meets your ad provider’s display requirements.

Get Started

Content

Display

Build Your Experience

Users & Data

Video overlay modes

Custom video overlays

The FeedOverlay protocol

Registering your overlay

SwiftUI overlays

ShortKitPlayer

Reactive streams

Commands

ContentItem

Example: scrubber with seek thumbnails

Feed scroll control

Example: closed captions

Engagement signals

Carousel, survey, and ad overlay modes

Custom carousel overlays

Video carousel overlays

Per-feed overlay binding (React Native)

Custom survey overlays

Custom ad overlays

​Video overlay modes

​Custom video overlays

​The FeedOverlay protocol

​Registering your overlay

​SwiftUI overlays

​ShortKitPlayer

​Reactive streams

​Commands

​ContentItem

​Example: scrubber with seek thumbnails

​Feed scroll control

​Example: closed captions

​Engagement signals

​Carousel, survey, and ad overlay modes

​Custom carousel overlays

​Video carousel overlays

​Per-feed overlay binding (React Native)

​Custom survey overlays

​Custom ad overlays

Video overlay modes

Custom video overlays

The FeedOverlay protocol

Registering your overlay

SwiftUI overlays

ShortKitPlayer

Reactive streams

Commands

ContentItem

Example: scrubber with seek thumbnails

Feed scroll control

Example: closed captions

Engagement signals

Carousel, survey, and ad overlay modes

Custom carousel overlays

Video carousel overlays

Per-feed overlay binding (React Native)

Custom survey overlays

Custom ad overlays