Skip to main content
The player, widget and tile group components let you embed short-form video outside the full-screen feed. Use the player for a single video (hero sections, product pages, inline previews), the widget for a horizontal carousel or vertical grid of video cards (home screens, dashboards, discovery surfaces), and a tile group when you own the layout and want the SDK to own playback (story rings, bespoke grids, tiles mixed into your own collection views). The player and widget require content fetched via 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, fetch ContentItem objects from the ShortKit API:
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

ViewController.swift

Activate and deactivate

The player does not manage its own visibility lifecycle. Call activate() 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:
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:
GridSide values: .left (default), .right.

WidgetInput

WidgetInput describes a video by its playback ID. Pass an array of these to configure(with:) or appendItems(_:).
Because ContentItem.playbackId is optional, use compactMap when converting from fetchContent() results:

Embedding a widget

ViewController.swift

Widget properties and callbacks

These properties are set on the widget component after initialization.
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

Use WidgetLayout.grid to replace the carousel with a vertical grid. The example below embeds a scrollable standalone grid that fills its assigned frame:
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 — set scrollable: false. The grid expands to fit all of its content and lets the parent scroll view handle scrolling. Three additional steps are required:
  1. Resize the container as items load. Subscribe to onContentHeightChange and update your height constraint whenever the grid’s content height changes.
  2. Forward scroll events. Call parentScrollViewDidScroll(_:) from the parent scroll view delegate so the widget can correctly score which grid cells are visible.
  3. Append items for pagination. Call appendItems(_:) to load additional items without a full reload.
ViewController.swift
To size the grid container before items load, use preferredGridHeight(forContainerWidth:itemCount:):

Appending items

Call appendItems(_:) 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.
When 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 (singleVisibleRotating mode). Each card plays until its preview clip finishes, then the carousel moves to the next card. rotationInterval has no effect on iOS.
  • Android and React Native — advancement is timer-based: the carousel advances to the next card after rotationInterval elapses, regardless of playback position.
On all platforms, when the carousel reaches the last card it wraps back to the first. Rotation pauses while the user is actively swiping and resumes once the gesture ends.
The rotationInterval unit differs across platforms. Android and React Native expect milliseconds (e.g. 10_000 / 10000). The property is ignored on iOS.

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 its WidgetConfig 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.
A tile that outlives its group falls back to its poster.
Keep one autoplaying group per screen: several groups on one screen compete for the same player pool, so gate all but one with setActive(false).

Ready for display

Web only (SDK 0.6.0+). iOS, Android and React Native parity is planned.
Each tile reports when its media is on screen: its poster (or first frame) has loaded, or its preview has started. Use it to show a placeholder in each cell until there is something to show, and to hold back chrome you draw over the tile. It fires once each time the tile is bound to an item. When a tile is given a different item, it resets and fires again once that item’s media shows. If a tile’s poster fails to load, it reports ready only once its preview starts; a tile whose poster fails and that never previews stays on its placeholder.
Not yet supported on iOS.

Per-tile feeds

iOS only (SDK 0.3.1+). Android, React Native and Web parity is planned.
By default every tile in a group opens the same feed — 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.
The group gives each tile a clip no earlier tile already shows, so the same item never appears in two rings even when an unfiltered feed overlaps a filtered one. A feed whose page is exhausted by that rule yields no tile and is omitted from 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: