Views and configuration

A view renders Storyteller content into a container element on your page. This page lists the constructor of each view class, the properties and methods that views share, and the configuration interfaces. For layout and setup tasks, see Choose a view and Configure views.

View classes

The SDK exports six view classes:

Class	Shows	Content argument	Configuration input	Delegate
StorytellerStoriesRowView	Stories in a horizontal row	Optional category IDs	IListConfiguration<'StorytellerStoriesRowView'>	IListViewDelegate
StorytellerStoriesGridView	Stories in a grid	Optional category IDs	IListConfiguration<'StorytellerStoriesGridView'>	IListViewDelegate
StorytellerClipsRowView	Clips in a horizontal row	Collection ID	IListConfiguration<'StorytellerClipsRowView'>	IListViewDelegate
StorytellerClipsGridView	Clips in a grid	Collection ID	IListConfiguration<'StorytellerClipsGridView'>	IListViewDelegate
StorytellerClipsPlayerView	A Clips player mounted in the page	Collection ID, { clipId }, or { externalId }	IStorytellerClipsPlayerConfiguration	IStorytellerClipsPlayerDelegate
StorytellerEmbeddedClipsPlayerView	A Clips player that fills a fixed area of the page	Collection ID, { clipId }, or { externalId }	IStorytellerEmbeddedClipsPlayerConfiguration	IStorytellerClipsPlayerDelegate

Create a view after initialize resolves, and call destroy before your application removes the container.

Constructors

Each constructor takes the container element ID first. The constructor renders the view and starts loading its content.

StorytellerStoriesRowView

new StorytellerStoriesRowView(
  elementId: string,
  listCategories?: string[],
  useGoogleWebStoryUrls?: boolean
)

Parameter	Type	Required	Default	Description
elementId	string	Yes	None	ID of the container element
listCategories	string[]	No	[]	Story category IDs. With no categories, the row shows the Stories in the Home list
useGoogleWebStoryUrls	boolean	No	false	true turns each Story tile into a link to the Story's Google Web Story URL, when the API provides one, instead of opening the SDK player

const storyRow = new Storyteller.StorytellerStoriesRowView(
  'stories-row-id',
  ['category-id']
);

• Guide: Add a Story or Clips row

StorytellerStoriesGridView

new StorytellerStoriesGridView(
  elementId: string,
  listCategories?: string[],
  useGoogleWebStoryUrls?: boolean
)

The parameters match StorytellerStoriesRowView.

• Guide: Add a Story or Clips grid

StorytellerClipsRowView

new StorytellerClipsRowView(
  elementId: string,
  collectionName: string,
  useGoogleWebStoryUrls?: boolean
)

Parameter	Type	Required	Default	Description
elementId	string	Yes	None	ID of the container element
collectionName	string	Yes	None	Clips collection ID. With an empty ID, the view loads no Clips
useGoogleWebStoryUrls	boolean	No	false	Accepted for parity with Stories views. It has no effect on Clips

The declarations also list a fourth argument, { deferInitialization?: boolean }. The SDK's player views use it to delay loading. Leave it out: with deferInitialization: true, a row or grid never loads.

const clipsRow = new Storyteller.StorytellerClipsRowView(
  'clips-row-id',
  'collection-id'
);

• Guide: Add a Story or Clips row

StorytellerClipsGridView

new StorytellerClipsGridView(
  elementId: string,
  collectionName: string,
  useGoogleWebStoryUrls?: boolean
)

The parameters match StorytellerClipsRowView.

• Guide: Add a Story or Clips grid

StorytellerClipsPlayerView

new StorytellerClipsPlayerView(
  elementId: string,
  source: string | StorytellerClipsPlayerSource,
  useGoogleWebStoryUrls?: boolean
)

Parameter	Type	Required	Default	Description
elementId	string	Yes	None	ID of the container element
source	string or StorytellerClipsPlayerSource	Yes	None	A collection ID string, or an object with exactly one of collection, clipId, or externalId
useGoogleWebStoryUrls	boolean	No	false	Accepted for parity with Stories views. It has no effect on Clips

StorytellerClipsPlayerSource has three optional fields. Set exactly one of them to a non-empty value:

interface StorytellerClipsPlayerSource {
  collection?: string;
  clipId?: string;
  externalId?: string;
}

A collection source plays the collection and supports collection navigation. A clipId or externalId source plays one Clip.

The constructor throws an Error for an object source with more than one value or with none:

Source	Error message
More than one non-empty field	StorytellerClipsPlayerView only supports one source at a time. Provide exactly one of `collection`, `clipId`, or `externalId`.
No non-empty field	StorytellerClipsPlayerView requires one of `collection`, `clipId`, or `externalId`.

const clipPlayer = new Storyteller.StorytellerClipsPlayerView(
  'clips-player-id',
  { externalId: 'clip-external-id' }
);

• Since: 10.1.0. Single-Clip sources were added in 10.13.6
• Guide: Clips player initialization

StorytellerEmbeddedClipsPlayerView

new StorytellerEmbeddedClipsPlayerView(
  elementId: string,
  source: string | StorytellerClipsPlayerSource,
  useGoogleWebStoryUrls?: boolean
)

The class extends StorytellerClipsPlayerView, so its parameters, source rules, errors, and members match that class. It differs in these ways:

• The player shows one Clip at a time and fills the container. Size the container with CSS
• The player does not lock page scrolling. Wheel input over the player stays in the player instead of scrolling the page
• Storyteller.sharedInstance.dismissPlayer does not close it

The embedded player suits a fixed area of your layout, such as a live blog or match centre.

• Since: 10.13.7
• Guide: Add a Clips player to a page

Deprecated aliases

RowView and GridView are deprecated aliases of StorytellerStoriesRowView and StorytellerStoriesGridView. They reference the same classes. Use the full names in new code.

Container element

The constructors read the container element when you call them:

• The element must exist. Otherwise, the SDK logs No element with ID <elementId> was found. The Storyteller view couldn't be initialized. as a console error, and the view renders nothing
• Use an ID with ASCII letters, numbers, -, and _. An ID that is not a valid CSS selector logs a warning when logging is enabled
• The SDK adds the storyteller class and a storyteller-view-id attribute to the element

The element can also carry these attributes, which the constructor reads once:

Attribute	Values	Views	Effect
data-ui-style	auto, light, dark	All	Initial uiStyle
data-cell-type	round, square	StorytellerStoriesRowView, StorytellerClipsRowView	Initial tile shape
data-base-url	A basename	All	Basename to use when configuration.basename is not set

A row fills the height of its container, so give the container a height. See the note in Add a Story or Clips row.

Members of every view

Every view class has these members.

configuration

set configuration(configuration: Partial<ListConfiguration<ViewName>>)
get configuration(): ListConfiguration<ViewName>

ViewName is the class name, such as 'StorytellerStoriesRowView'. The two Clips player classes both use 'StorytellerClipsPlayerView', and their setter takes IStorytellerClipsPlayerConfiguration. ListConfiguration is not exported. Assign an IListConfiguration value instead.

Assigning an object updates only the fields that it includes:

• A change to categories, collection, clipId, or externalId reloads the view's content
• A change to theme or uiStyle rebuilds the view theme
• A displayLimit field set to undefined or 0 removes the limit
• A context change applies to later activity events

Reading the property returns the current values, including the view theme that the SDK merged from the global theme and configuration.theme.

storyRow.configuration = {
  categories: ['category-id'],
  displayLimit: 10,
  uiStyle: Storyteller.UiStyle.dark,
};

• Since: 10.0.0
• Guide: Configure views

delegate

get delegate(): IListViewDelegate
set delegate(delegateObj: IListViewDelegate)

The view's callbacks. The Clips player classes use IStorytellerClipsPlayerDelegate. Assigning an object replaces the previous delegate. The SDK fills callbacks that you leave out with no-op functions.

storyRow.delegate = {
  onDataLoadComplete: (success, error, dataCount) => {
    const container = document.getElementById('stories-row-id');

    if (container) {
      container.hidden = !success || dataCount === 0;
    }
  },
};

• Type: IListViewDelegate
• Guide: Handle view callbacks

reloadData

reloadData(): Promise<void>

Loads fresh content for the view from the API. Clips views load the first page again. The view calls onDataLoadStarted, then onDataLoadComplete with the result.

• Returns: a promise that resolves after the load finishes. A failed load resolves too and reports the error through onDataLoadComplete
• Guide: reloadData

destroy

destroy(): void

Releases the view. The SDK unmounts the view from the container, removes the view's player container unless another view shares it, and stops theme updates for the view. A second call does nothing. Call destroy before your application removes or replaces the container, such as in a React effect cleanup.

• Guides: Use React or Next.js, Troubleshoot page transitions

Deprecated view members

These members still work in 11.0.0. Replace them with configuration or the shared instance:

Member	Views	Replacement
theme (get and set)	All	configuration.theme
uiStyle (get and set)	All	configuration.uiStyle
displayLimit (get and set)	All	configuration.displayLimit
categories (get and set)	Stories views	configuration.categories. The setter does not reload the view
cellType (set)	StorytellerStoriesRowView	configuration.cellType
openStory(id: string): void	Stories views	Storyteller.sharedInstance.openStory
openPage(pageId: string, onError?: (message: string) => void): void	Stories views	Storyteller.sharedInstance.openPage

Members of some views

These members exist only on the classes listed.

cellType

set cellType(type: StorytellerListViewCellType)

Available on StorytellerClipsRowView. Sets the tile shape to CellType.round or CellType.square. The Clips row configuration has no cellType field, so use this setter or the data-cell-type attribute. For StorytellerStoriesRowView, use configuration.cellType.

• Guide: cellType

topLevelBackButtonEnabled

get topLevelBackButtonEnabled(): boolean
set topLevelBackButtonEnabled(isEnabled: boolean)

Available on StorytellerClipsPlayerView and StorytellerEmbeddedClipsPlayerView. true shows a back button at the top of the player. A tap calls onTopLevelBackTapped, or window.history.back() when the delegate has no such callback. The default is false. This property is not part of configuration.

clipPlayer.topLevelBackButtonEnabled = true;
clipPlayer.delegate = {
  onTopLevelBackTapped: () => {
    window.history.back();
  },
};

• Since: 10.13.6
• Guide: topLevelBackButtonEnabled

Configuration

The configuration interfaces describe what you can assign to a view's configuration property.

IListConfiguration

type IListConfiguration<
  ListType extends keyof ListTypeToConfigMap | void = void
>

ListTypeToConfigMap is an internal map from each view class name to its fields. Pass a view class name as the type argument to select the fields for that view. Every field is optional:

Type argument	Fields
None	basename, context, displayLimit, theme, uiStyle
'StorytellerStoriesRowView'	The fields for no type argument, plus categories, preload, cellType
'StorytellerStoriesGridView'	The fields for no type argument, plus categories, preload
'StorytellerClipsRowView', 'StorytellerClipsGridView'	The fields for no type argument, plus collection
'StorytellerClipsPlayerView', 'StorytellerEmbeddedClipsPlayerView'	The fields for no type argument, plus collection, clipId, externalId

The fields have these types and defaults:

Field	Type	Views	Default	Description
basename	string	All	stories or clips. With several views on a page, a value derived from the categories or collection	First segment of the player hash URL. The SDK keeps only ASCII letters, numbers, -, and _
categories	string[]	Stories views	The constructor listCategories	Story category IDs
cellType	CellType	StorytellerStoriesRowView	CellType.square, or the data-cell-type attribute	Tile shape
collection	string	Clips views	The constructor collection	Clips collection ID
clipId	string	Clips players	None	Clip ID for single-Clip playback
externalId	string	Clips players	None	Clip external ID for single-Clip playback
context	unknown	All	undefined	Your attribution data. The SDK returns it in UserActivityData.context
displayLimit	number	Rows and grids. The player types accept it too	No limit	Maximum number of tiles
preload	boolean	Stories views	false	true starts more Story player work before the first open. Assigning false later does not undo true
theme	Subset<UiTheme>	All	The global theme	View theme. The SDK merges it over Storyteller.sharedInstance.theme
uiStyle	UiStyle	All	UiStyle.auto, or the data-ui-style attribute	Light, dark, or system color scheme

type RowConfiguration =
  Storyteller.IListConfiguration<'StorytellerStoriesRowView'>;

const rowConfiguration: RowConfiguration = {
  basename: 'top-stories',
  cellType: Storyteller.CellType.round,
  context: { location: 'home' },
};

storyRow.configuration = rowConfiguration;

• Since: 10.0.0. context was added in 10.13.17
• Guide: Configure views

Clips player configuration types

type IStorytellerClipsPlayerConfiguration =
  Partial<StorytellerClipsPlayerConfiguration>;

type IStorytellerEmbeddedClipsPlayerConfiguration =
  Partial<StorytellerClipsPlayerConfiguration>;

Both types have the same fields as IListConfiguration<'StorytellerClipsPlayerView'>: basename, context, displayLimit, theme, uiStyle, collection, clipId, and externalId. Their theme field also accepts a full IUiTheme.

An update that includes a source field changes the source. Include exactly one non-empty source field. Otherwise, the SDK logs an error and keeps the current source.

clipPlayer.configuration = {
  externalId: 'new-clip-external-id',
};

• Guides: Clips player configuration, Embedded Clips player configuration