Ordering and item limits

Several data source types share the same order type, advanced order, and item count options. Use this page as the shared reference when you configure Labels, IDs, or Recommendations.

For CMS-configured widgets, ordering and limits can be set in the CMS widget builder. See CMS-configured widgets.

Order types

Type	Description
`manual`	Items follow a manually defined order
`recentlyUpdatedFirst`	Most recently updated items appear first
`recentlyUpdatedLast`	Least recently (oldest) updated items appear first
`atoz`	Sort alphabetically (A–Z)
`ztoa`	Sort alphabetically (Z–A)
`recentlyCreatedFirst`	Newest content appears first
`recentlyCreatedLast`	Oldest content appears first
`random`	Content is shown in random order

Advanced order type

Type	Description
`liveFirst`	Prioritizes live content above all others. Overrides both `orderType` and `labelsPriority`. When read-status ordering is enabled (the default), items sort as: live unread, live read, non-live unread, non-live read.

Read-status ordering

Widgets reorder items so unread content appears before read content. This uses the widget property shouldOrderWidgetByReadStatus (default true), not the data source type. It applies to row and grid widgets for Stories, Moments, and Videos.

Setting	Result
`true` (default)	Unread items appear before read items within the widget.
`false`	Read/unread does not affect order. Items follow `orderType`, server order, or manual list order.

When every item in the widget has been viewed, the SDK keeps the original item order.

On the Web SDK, when orderType is manual, read/unread sorting does not override the manual sequence.

Ordering vs filtering out read content

Reordering by read status is not the same as removing read content from the feed. With the default setting, already-viewed items still appear in the widget, but after unread items. To hide viewed content entirely, the app owner must track viewed content IDs and exclude them when building the data source (for example, an IDs data source with only unviewed IDs). See Experiences FAQ 1 for the common integration question.

Configure the property on each platform: Widgets — iOS, Widgets — Android, WidgetView class, Widgets React Native. Player containers use separate read-order flags (for example, shouldOrderContentByReadStatus); configure those on the player API.

Item count limits

Setting	Type	Description
`maxItems`	number	Total number of items available in the widget and player
`maxDisplayItemsCount`	number	Maximum number of items visible in the widget preview