fetchContent(). A tile group can be host-seeded the same way, or fetch its own content per tile.
Flutter: Single player and widget components are coming soon for the Flutter SDK. For now, use the full-screen feed via
ShortKitFeed.Fetching content
Before displaying videos, fetchContentItem objects from the ShortKit API:
- iOS (Swift)
- Android
- React Native
- Web
fetchContent(limit:filter:) returns an array of resolved ContentItem objects with streaming URLs, metadata, and captions. limit defaults to 10. Pass a FeedFilter to restrict results by tags, section, author, content type, or custom metadata. For full model definitions see the Content Types guide.
Single player
PlayerConfig
Embedding a player
- iOS (UIKit)
- iOS (SwiftUI)
- Android
- React Native
- Web
ViewController.swift
Activate and deactivate
The player does not manage its own visibility lifecycle. Callactivate() when the player is on screen and deactivate() when it leaves. This gives you full control over playback in scroll views, tab bars, and navigation stacks.
On React Native, use the
active prop instead of method calls. It defaults to the value of config.autoplay (which is true by default). Set it to false to pause and true to resume.
Widget
The widget displays a horizontal carousel or vertical grid of video cards with muted autoplay. Tapping a card opens the feed by default.WidgetConfig
Layout
WidgetConfig.layout controls whether the widget renders as a horizontal carousel or a vertical grid.
Grid parameters:
Two helper methods on
WidgetConfig make it easier to size the container when using a non-scrollable embedded grid:
- iOS (Swift)
- Android
- React Native
gridCellHeight returns nil for carousel layouts. preferredGridHeight returns nil for carousel layouts and for scrollable grid layouts (where total height is unbounded).Playback mode
WidgetConfig.playbackMode controls how the widget activates preview playback across its cells.
The
startSide parameter on gridAlternating controls which column plays in the first row:
- iOS (Swift)
- Android
- React Native
GridSide values: .left (default), .right.WidgetInput
WidgetInput describes a video by its playback ID. Pass an array of these to configure(with:) or appendItems(_:).
- iOS (Swift)
- Android
- React Native
Because
ContentItem.playbackId is optional, use compactMap when converting from fetchContent() results:Embedding a widget
- iOS (UIKit)
- Android
- React Native
- Web
ViewController.swift
Widget properties and callbacks
These properties are set on the widget component after initialization.- iOS (Swift)
- Android
- React Native
Set these directly on your
ShortKitWidgetViewController instance:setFeedItems(_ inputs: [FeedInput]) supplies an optional seed list of items for the full-screen feed that opens when a card is tapped. The widget’s own cards are always prepended so the tapped clip is the opening item; the seed items follow. FeedInput accepts the same inputs as the full-screen feed — see Embedding a Feed for details.Embedding a grid
UseWidgetLayout.grid to replace the carousel with a vertical grid. The example below embeds a scrollable standalone grid that fills its assigned frame:
- iOS (UIKit)
- Android
- React Native
ViewController.swift
Embedded (non-scrollable) grid
When the grid sits inside a host-managed scroll view alongside other content — for example, a home screen with a carousel above and a grid below — setscrollable: false. The grid expands to fit all of its content and lets the parent scroll view handle scrolling.
Three additional steps are required:
- Resize the container as items load. Subscribe to
onContentHeightChangeand update your height constraint whenever the grid’s content height changes. - Forward scroll events. Call
parentScrollViewDidScroll(_:)from the parent scroll view delegate so the widget can correctly score which grid cells are visible. - Append items for pagination. Call
appendItems(_:)to load additional items without a full reload.
- iOS (UIKit)
- Android
- React Native
ViewController.swift
preferredGridHeight(forContainerWidth:itemCount:):
Appending items
CallappendItems(_:) to add more items to the grid without a full reload — for example, when the user scrolls near the bottom:
appendItems is a no-op on an empty input array. It works on both scrollable and non-scrollable grid layouts, inserting items incrementally without a full reload. On carousel layouts it triggers a full reload instead.
Auto-rotation
Auto-rotation applies to carousel layout only (
WidgetLayout.carousel). Grid layouts use the playbackMode setting to control preview activation instead.autoplay is true (the default), the carousel widget automatically advances through cards. How advancement is triggered differs by platform:
- iOS — advancement is driven by the preview reaching its end (
singleVisibleRotatingmode). Each card plays until its preview clip finishes, then the carousel moves to the next card.rotationIntervalhas no effect on iOS. - Android and React Native — advancement is timer-based: the carousel advances to the next card after
rotationIntervalelapses, regardless of playback position.
Tile groups
A tile group is the widget without the layout. You place tiles wherever you like — a horizontal stack of story rings, cells in your own list or collection view, a bespoke grid — and the group owns everything media-related: which tile previews (visibility scan plus the same preview-driven rotation as the widget), player leasing, poster prefetch around the visible window, and tap → full-screen feed with the widget’s zoom-from-tile transition.Tile groups are available on iOS, Android, React Native and Web (SDK 0.6.0+). Per-tile feeds (below) are iOS-only for now.
TileGroupConfig
Every field has the same meaning as itsWidgetConfig counterpart. There are no layout fields, because you own the layout.
Web: enum values are strings (
playbackMode: 'singleVisibleRotating', clickAction: 'feed'), times are in seconds, and the prefetch horizon is one field, prefetch: { ahead: 4, behind: 1 }. Web also accepts filter, the filter for the feed opened on tap when feedConfig sets none, and presentation, the placement of that feed.Embedding tiles
Create one group per surface, hand each tile to it, and tell the group which item the tile renders. The group reads each tile’s frame to decide what previews; it never moves or sizes a tile.- iOS (Swift)
- Web
setActive(false).
Ready for display
Web only (SDK 0.6.0+). iOS, Android and React Native parity is planned.
- iOS (Swift)
- Android
- React Native
- Web
Not yet supported on iOS.
Per-tile feeds
iOS only (SDK 0.3.1+). Android, React Native and Web parity is planned.
config.feedConfig — at the tapped item’s position, exactly like widget cards. A row of story rings needs the opposite: each ring is an entry point into a different feed. “Trending” opens the unfiltered feed, “Baseball” opens FeedFilter(tags: ["baseball"]), “Hockey” opens tags: ["hockey"], each starting on the clip the ring was showing.
Build the group from a list of TileFeeds instead of seeding items, and the group fetches the first page of each feed itself. Each tile’s preview is its feed’s first clip, and tapping it opens that feed with the filter already applied, the tapped clip still playing, the rest of the page queued behind it, and pagination continuing on the server with the same filter. Nothing reloads, and every item carries its full metadata.
onTilesLoaded.
On a self-fetching group, setItems, setFeedItems and bindContent are no-ops; the group owns its items.
Preview progress
Two callbacks report what the group is doing, so you can draw a progress ring or highlight the active tile without running your own timer:onTileFeedOpened, onAutoplayTileChanged and onAutoplayTileTime also fire on host-seeded groups, carrying the playback ID instead of a feed id. They are distinct from onPreviewTileChanged, which reports hold-to-preview pins, not rotation.
Click actions
PlayerConfig.clickAction, WidgetConfig.clickAction and TileGroupConfig.clickAction accept the same values: