Widgets

Widgets are UI components that preview content and help viewers discover Stories, Moments, and Videos. You can place widgets anywhere in your app UI.

To learn how widgets fit into player sources, see Player sources.

What widgets do

• Preview content without interrupting the viewer journey
• Open the player to the selected Story, Moment, or Video
• Open a Moment into a fullscreen Moments tabs player on iOS and Android (multiple feeds as tabs)
• Support styling so the widget matches your app design

Widget layout examples

Experiences support common layout patterns such as horizontal rows and vertical grids.

If you use the Experiences Web SDK, you can also embed inline video playback in a page region using WidgetEmbeddedVideo. See WidgetEmbeddedVideo.

Horizontal scroll single line list widget

A horizontal, scrollable row for browsing Stories. Best suited for a small set of Stories or compact areas in the app interface.

Vertical scrolling grid widget

A vertical, scrollable grid for browsing Stories and Moments. Suited for larger content collections or dedicated sections of the app.

Widget configuration

The layout examples above show orientation and presentation. Every widget is also defined by content, data source, and design settings. Widgets can be configured in app code or in Experiences CMS. The configuration areas are similar:

• Content type: Stories, Moments, or Videos
• Data source: how content is selected, including label rules associated with the widget
• Layout and orientation: row, grid, or single-line presentation; horizontal or vertical scrolling
• Design: colors, fonts, spacing, item shape, and component visibility

The Experiences SDK applies these settings when the widget loads and displays content. See Widget appearance for widget look-and-feel concepts.

Widget items

A widget item is a single element within a widget. Each represents a Story, Moment, or Video and acts as a link to open that content in the player.

Item components

Each item can include:

• Thumbnail image: preview of the Story, Moment, or Video
• Title: short label describing the content
• Read/unread indicator: shows whether the viewer has already seen the item. By default, widgets reorder items so unread content appears first (shouldOrderWidgetByReadStatus, default true). Already-viewed items remain in the widget but appear after unread items. See Ordering and item limits.
• Chip: marks the content as live or newly published

Item styling

Widget items can be tailored to match your app design. Width, height, and corner radius can be configured per widget or globally.

Shape presets include:

• Circle items: best for thumbnail-focused content
• 2:3 rectangles: allow room for thumbnails, titles, and indicators

Display limits

There is an important distinction between maxItems in Data sources and maxDisplayItemsCount in the widget layout:

• maxDisplayItemsCount: limits the number of items shown in the widget. Additional content remains accessible once the player is opened. For example, a widget may display one item but reveal more in the player.
• maxItems: limits the total number of items available in the widget and the player

Code-configured and CMS-configured widgets

You can configure a widget in app code or in Experiences CMS.

When to use each:

• Code-configured widgets: developers own the full integration, or the widget needs advanced design or data source logic.
• CMS-configured widgets: content managers update supported settings in CMS without a developer change each time. Initialize the widget with a local layout and data source as a fallback if the CMS request fails.

See Widget builder how to for the CMS workflow and handoff.

See CMS-configured widgets for the developer path.

Integrate widgets in code

For code-configured widgets, add the widget to your app view hierarchy and set the data source, layout, and design in code.

See Widgets: iOS, Widgets: Android, and Widget appearance.