Themes#

The appearance of the SDK can be customized by setting the theme prop. This requires a Theme configurable object.

    const globalTheme: Theme = {
        ...
    }
    StorytellerSdk.setTheme(globalTheme)

This object is used as the global theme for every StorytellerListView included in your application. We, therefore, recommend setting it as early as possible in the application's lifecycle.

It is also possible to apply a specific theme to a specific StorytellerListView instance. For example:

    const myTheme: Theme = {
        ...
    }

    ...
    <StorytellerStoriesRowView
        ...
        theme={myTheme}
    />

For more information on setting a theme on an individual list, see StorytellerListView.

Configuring a UiTheme#

A Theme consists of the following properties:

light sets the ThemeType to apply for light mode.
dark sets the ThemeType to apply for dark mode.

Creating Themes#

A Theme contains theme customizations for various components in the SDK. All properties are optional.

Some properties take their default value from others. For example, setting the primaryColor to #FF0000 will also result in the New Indicator for Rectangular Tiles being colored red. Such properties are indicated in the table below.

Note that theme properties may be used for other situations in future.

Colors#

The colors property on theme is used to establish a set of base colors for the SDK to use.

Property	Default Value	Data Type	Description
`primary`	`#1C62EB`	`ARGB string`	The default accent color used throughout the UI. In general, this should be the primary brand color.
`success`	`#3BB327`	`ARGB string`	Used to indicate correct answers in Quizzes.
`alert`	`#E21219`	`ARGB string`	Used to indicate incorrect answers in Quizzes.
`white.primary`	`#FFFFFF`	`ARGB string`	Used for white text
`white.secondary`	`white.primary` at 85% opacity	`ARGB string`	Used for light text
`white.tertiary`	`white.primary` at 70% opacity	`ARGB string`	Used for gray text
`black.primary`	`#000000`	`ARGB string`	Used for black text
`black.secondary`	`black.primary` at 85% opacity	`ARGB string`	Used for light black text
`black.tertiary`	`black.primary` at 70% opacity	`ARGB string`	Used for gray text

Primitives#

The primitives object contains base values which are used throughout the SDK.

Property	Default Value	Data Type	Description
`cornerRadius`	`8`	`number`	The corner radius used for rectangular tiles, buttons and poll/quiz answers

Lists#

The lists customizes properties of the various list types available from the SDK.

Property	Default Value	Data Type	Description
`row.tileSpacing`	`8`	`number`	The space between each Tile in a row
`row.startInset`	`12`	`number`	The space before the first Tile in a row
`row.endInset`	`12`	`number`	The space after the last Tile in a row
`grid.tileSpacing`	`8`	`number`	The space between each Tile in a grid, both vertically and horizontally
`grid.columns`	`2`	`number`	The number of columns in a grid
`grid.topInset`	`12`	`number`	The space before the first row in a grid
`grid.bottomInset`	`12`	`number`	The space after the last row in a grid
`backgroundColor`	`colors.white.primary` (light mode), `colors.black.primary` (dark mode)	`ARGB string`	Required for outline on Live chip and fade to the side of the row.
`title.font`	`null`	`FontProvider`	Defines the font of the Title in Section
`title.textSize`	`22`	`number`	Size of the Title in Section
`title.lineHeight`	`28`	`number`	The line height of the Title in Section
`title.textCase`	`default`	`TextCase`	Sets the text case for the Title in Section. Possible values are `upper`, `lower` and `default`
`title.textColor`	`null`	`ARGB string`	Color of Title in Section
`animateTilesOnReorder`	`true`	`boolean`	When the `reloadData()` method is called to update lists, a reorder animation is added to visualise the updating process.
`enablePlayerOpen`	`true`	`boolean`	Controls whether tapping a list tile opens the Storyteller player automatically. Set to `false` only when your app intentionally handles tile taps itself.

Gradient#

The ThemeGradient struct allows for the creation of a color gradient, with options to customize both the colors and the positions at which the gradient starts and ends.

Android 11.6.3 correctly honors the numeric GradientPosition enum values. Untyped JavaScript themes that omit either position retain the compatibility defaults of topLeft for the start and bottomRight for the end.

Property	Default Value	Data Type	Description
`startColor`	`null`	`ARGB string`	The color where the gradient begins.
`endColor`	`null`	`ARGB string`	The color where the gradient ends.
`startPosition`	`topLeft`	`GradientPosition`	The position indicating where the gradient starts.
`endPosition`	`bottomRight`	`GradientPosition`	The position indicating where the gradient ends.

Enum: GradientPosition#

Defines positions for starting and ending points of the gradient.

Value	Data Type	Description
`'bottomLeft'`	`string`	Bottom left corner of the gradient area.
`'bottomCenter'`	`string`	Bottom center edge of the gradient area.
`'bottomRight'`	`string`	Bottom right corner of the gradient area.
`'centerLeft'`	`string`	Center left edge of the gradient area.
`'centerCenter'`	`string`	Center of the gradient area.
`'centerRight'`	`string`	Center right edge of the gradient area.
`'topLeft'`	`string`	Top left corner of the gradient area.
`'topCenter'`	`string`	Top center edge of the gradient area.
`'topRight'`	`string`	Top right corner of the gradient area.

Tiles#

The tiles property can be used to customize the appearance of the Tiles.

Property	Default Value	Data Type	Description
`title.textSize`	`11`	`number`	The size of the Title on a Tile
`title.lineHeight`	`13`	`number`	The line height of the Title on a Tile
`title.alignment`	`center`	`ElementAlignment`	The alignment of the Title on a Tile. Possible values are `left`, `center` and `right`
`circularTile.title.unreadTextColor`	inherits `colors.black.primary` for `light`, `colors.white.primary` for `dark`	`ARGB string`	The text color of the Title for a circular Tile when the item is unread
`circularTile.title.readTextColor`	inherits `colors.black.tertiary` for `light`, `colors.white.tertiary` for `dark`	`ARGB string`	The text color of the Title for a circular Tile when the item is read
`circularTile.unreadIndicatorColor`	inherits `colors.primary`	`ARGB string`	The color of the ring around a circular tile when the Story is unread
`circularTile.readIndicatorColor`	`#C5C5C5`	`ARGB string`	The color of the ring around a circular tile when the Story is read
`circularTile.unreadIndicatorGradient`	`null`	`ThemeGradient?`	The gradient of the ring around a circular tile when the story or the clip is unread. If set, overrides `circularTile.unreadIndicatorColor`
`circularTile.unreadBorderWidth`	`2`	`number`	The width of Circular a Tile ring border in unread state
`circularTile.readBorderWidth`	`2`	`number`	The width of a Circular Tile ring border in read state
`circularTile.liveChip.readImage`	`null`	`ImageSource?`	Image to be used in place of default read Live Indicator
`circularTile.liveChip.unreadImage`	`null`	`ImageSource?`	Image to be used in place of default unread Live Indicator
`circularTile.liveChip.unreadBackgroundColor`	`colors.alert`	`ARGB string`	Background color of the Live Indicator when the story contains unread pages or the clip has not been viewed
`circularTile.liveChip.readBackgroundColor`	`colors.black.tertiary`	`ARGB string`	Background color of the Live Indicator when all story pages have been read or the clip has been viewed
`circularTile.liveChip.unreadBackgroundGradient`	`null`	`ThemeGradient?`	The gradient of the ring around a live tile and background of the Live Indicator. If set, overrides `circularTile.liveChip.unreadBackgroundColor`
`circularTile.liveChip.unreadTextColor`	`colors.white.primary`	`ARGB string`	Text color of the Live Indicator when the story contains unread pages or the clip has not been viewed
`circularTile.liveChip.readTextColor`	`colors.white.primary`	`ARGB string`	Text color of the Live Indicator when all story pages have been read or the clip has been viewed
`chip.textSize`	`11`	`number`	Text size for the New Indicator and Live Indicator
`chip.alignment`	`right`	`ElementAlignment`	Alignment of the New Indicator and Live Indicator. Possible values are `left`, `center` and `right`
`chip.show`	`true`	`Boolean`	Used to show/hide the new/live chip
`rectangularTile.title.textColor`	inherits `colors.white.primary`	`ARGB string`	The text color of the Story Title for a rectangular tile
`rectangularTile.padding`	`8`	`number`	The internal padding for a rectangular tile
`rectangularTile.unreadIndicator.image`	`null`	`ImageSource?`	An image which can be used in place of the default unread indicator for a rectangular tile. If set, overrides `rectangularTile.unreadIndicator.gradient`
`rectangularTile.unreadIndicator.gradient`	`null`	`ThemeGradient?`	The background gradient of the unread indicator for a rectangular tile. If set, overrides `rectangularTile.unreadIndicator.backgroundColor`
`rectangularTile.unreadIndicator.backgroundColor`	inherits `colors.primary`	`ARGB string`	The background color of the unread indicator for a rectangular tile
`rectangularTile.unreadIndicator.alignment`	`right`	`ElementAlignment`	The alignment of the unread indicator on a rectangular tile. Possible values are `left`, `center` or `right`
`rectangularTile.unreadIndicator.textColor`	inherits `colors.white.primary`	`ARGB string`	The text color of the unread indicator for a rectangular tile
`rectangularTile.unreadIndicator.borderColor`	`null`	`ARGB string?`	Border color of the unread indicator for a rectangular tile
`rectangularTile.liveChip.readImage`	`null`	`ImageSource?`	Image to be used in place of default read Live Indicator
`rectangularTile.liveChip.unreadImage`	`null`	`ImageSource?`	Image to be used in place of default unread Live Indicator
`rectangularTile.liveChip.unreadBackgroundColor`	`colors.alert`	`ARGB string`	Background color of the Live Indicator when the story contains unread pages or the clip has not been viewed
`rectangularTile.liveChip.readBackgroundColor`	`colors.black.tertiary`	`ARGB string`	Background color of the Live Indicator when all story pages have been read or the clip has been viewed
`rectangularTile.liveChip.unreadBackgroundGradient`	`null`	`ThemeGradient?`	The gradient of the ring around a live tile and background of the Live Indicator. If set, overrides `rectangularTile.liveChip.unreadBackgroundColor`
`rectangularTile.liveChip.unreadTextColor`	`colors.white.primary`	`ARGB string`	Text color of the Live Indicator when the story contains unread pages or the clip has not been viewed
`rectangularTile.liveChip.readTextColor`	`colors.white.primary`	`ARGB string`	Text color of the Live Indicator when all story pages have been read or the clip has been viewed
`rectangularTile.liveChip.unreadBorderColor`	`null`	`ARGB string?`	Border color of the Live Indicator when the story contains unread pages or the clip has not been viewed.
`rectangularTile.liveChip.readBorderColor`	`null`	`ARGB string?`	Border color of the Live Indicator when all story pages have been read or the clip has been viewed.

Diagram illustrating rowTheme options

Player#

iOS 11.6.0 and Android 11.6.3 map clips.topGradient, bottomGradient, feed-switcher/title/category typography, progress-bar position and colours, and four Embedded Clips spacing fields. Omitted or invalid fields preserve native defaults.

The player property is used to customize properties relating to the Story Player.

Property	Default Value	Data Type	Description
`showStoryIcon`	`false`	`Boolean`	Shows the round Story icon before the Story Title in the Player
`showTimestamp`	`true`	`Boolean`	Shows the timestamp after the Story Title in the Player, indicating how long ago a Story was published
`showShareButton`	`true`	`Boolean`	Shows the share button in the Player. Setting this to `false` entirely disables sharing in Storyteller
`showLikeButton`	`true`	`Boolean`	Shows the like button in the Player. Setting this to `false` entirely disables liking in Storyteller
`showMoreButton`	`true`	`Boolean`	Shows the more/options button in the Player where supported
`enableFollowableCategorySwipeFromRightEdge`	`true`	`Boolean`	Enables the Clips followable category/profile screen swipe gesture from the right edge
`liveChip.image`	`null`	`ImageSource?`	Image used in place of Live Chip before Live Story or Clip Titles. If set, it overrides `liveChip.backgroundGradient`
`liveChip.textColor`	`null`	`ARGB string?`	Text color used for badge label for Live Story or Clip
`liveChip.backgroundGradient`	`null`	`ThemeGradient?`	Background gradient of the badge for Live Story or Clip. If set, it overrides `liveChip.backgroundColor`
`liveChip.backgroundColor`	`theme.colors.alert`	`ARGB string?`	Background color of the badge for Live Story or Clip
`liveChip.borderColor`	`null`	`ARGB string`	Border color of the badge for Live Story or Clip
`icons.share`	`null`	`ImageSource`	An image to be used in place of the default share icon
`icons.refresh`	`null`	`ImageSource`	Refresh button image to be used in place of default refresh icon
`icons.close`	`null`	`ImageSource`	Close button image to be used in place of default close icon
`icons.like.initial`	`null`	`ImageSource`	Initial like button image to be used in place of default initial like icon
`icons.like.liked`	`null`	`ImageSource`	Liked button image to be used in place of default liked icon
`icons.like.animation.liked`	`null`	`PlayerLikeAnimationResource?`	Lottie animation played when a Clips like button moves from unliked to liked
`icons.like.animation.unliked`	`null`	`PlayerLikeAnimationResource?`	Lottie animation played when a Clips like button moves from liked to unliked
`icons.back`	`null`	`ImageSource`	Back button image to be used in place of the default Clips back icon
`icons.more`	`null`	`ImageSource`	More/options button image to be used in place of the default icon where supported
`icons.mute.muted`	`null`	`ImageSource`	Image used for the mute button when audio is muted in Stories and Clips
`icons.mute.unmuted`	`null`	`ImageSource`	Image used for the mute button when audio is unmuted in Stories and Clips
`icons.captions.enabled`	`null`	`ImageSource`	Image used for the captions button when captions are enabled in Stories and Clips
`icons.captions.disabled`	`null`	`ImageSource`	Image used for the captions button when captions are disabled in Stories and Clips
`clips.showButtonBackgrounds`	`true`	`Boolean`	Controls whether Clips player action buttons render the default circular backgrounds
`clips.actionIconSize`	`32`	`number`	Size for Clips player action icons. Values outside the native supported range are clamped
`clips.topGradient`	native readability scrim	`ThemeGradient?`	iOS 11.6.0+ and Android 11.6.3+: top Clips readability gradient; a fully transparent gradient is a valid visual opt-out
`clips.bottomGradient`	native readability scrim	`ThemeGradient?`	iOS 11.6.0+ and Android 11.6.3+: bottom Clips readability gradient
`clips.feedSwitcher.selected.fontWeight`	native selected weight	`StorytellerFontWeight?`	iOS 11.6.0+ and Android 11.6.3+: selected For You/Following label weight
`clips.feedSwitcher.selected.textSize`	`15`	`number?`	iOS 11.6.0+ and Android 11.6.3+: selected feed label size
`clips.feedSwitcher.selected.lineHeight`	`20`	`number?`	iOS 11.6.0+ and Android 11.6.3+: selected feed label line height
`clips.feedSwitcher.unselected.fontWeight`	native unselected weight	`StorytellerFontWeight?`	iOS 11.6.0+ and Android 11.6.3+: unselected For You/Following label weight
`clips.feedSwitcher.unselected.textSize`	`15`	`number?`	iOS 11.6.0+ and Android 11.6.3+: unselected feed label size
`clips.feedSwitcher.unselected.lineHeight`	`20`	`number?`	iOS 11.6.0+ and Android 11.6.3+: unselected feed label line height
`clips.progressBar.position`	`bottom`	`StorytellerClipsProgressBarPosition?`	iOS 11.6.0+ and Android 11.6.3+: `bottom` or `aboveAction` for Embedded Clips
`clips.progressBar.playedColor`	native compatibility colour	`ARGB string?`	iOS 11.6.0+ and Android 11.6.3+: non-scrubbing played-track colour
`clips.progressBar.remainingColor`	native compatibility colour	`ARGB string?`	iOS 11.6.0+ and Android 11.6.3+: non-scrubbing remaining-track colour
`clips.progressBar.active.playedColor`	inherits configured base	`ARGB string?`	iOS 11.6.0+ and Android 11.6.3+: played-track colour while scrubbing
`clips.progressBar.active.remainingColor`	inherits configured base	`ARGB string?`	iOS 11.6.0+ and Android 11.6.3+: remaining-track colour while scrubbing
`clips.progressBar.active.currentTimeColor`	native compatibility colour	`ARGB string?`	iOS 11.6.0+ and Android 11.6.3+: current-time and separator colour while scrubbing
`clips.progressBar.active.totalTimeColor`	native compatibility colour	`ARGB string?`	iOS 11.6.0+ and Android 11.6.3+: total-duration colour while scrubbing
`clips.title.font`	inherits global font	`FontProvider?`	Custom font for the Clips player title
`clips.title.fontWeight`	native title weight	`StorytellerFontWeight?`	iOS 11.6.0+ and Android 11.6.3+: title font weight
`clips.title.textSize`	`16`	`number`	Text size for the Clips player title
`clips.title.lineHeight`	`null`	`number?`	Line height for the Clips player title
`clips.title.textColor`	inherits `colors.white.primary`	`ARGB string?`	Text color for the Clips player title
`clips.eyebrow.font`	inherits global font	`FontProvider?`	Custom font for the Clips player eyebrow text
`clips.eyebrow.textSize`	`15`	`number`	Text size for the Clips player eyebrow text
`clips.eyebrow.lineHeight`	`20`	`number?`	Line height for the Clips player eyebrow text
`clips.eyebrow.textColor`	inherits `colors.white.secondary`	`ARGB string?`	Text color for the Clips player eyebrow text
`clips.categoryNavigation.fontWeight`	`regular`	`StorytellerFontWeight?`	iOS 11.6.0+ and Android 11.6.3+: category-navigation label weight
`clips.categoryNavigation.textSize`	`16`	`number?`	iOS 11.6.0+ and Android 11.6.3+: category-navigation label size
`clips.categoryNavigation.lineHeight`	native font line height	`number?`	iOS 11.6.0+ and Android 11.6.3+: category-navigation label line height
`clips.spacing.backButtonStartInset`	`0`	`number`	Start inset for the Clips back or close button
`clips.spacing.contentInsetHorizontal`	`16`	`number`	Horizontal/top padding for Clips description and action content areas
`clips.spacing.contentInsetBottom`	`16`	`number`	Bottom padding for Clips description and action content areas
`clips.spacing.actionSpacing`	`12`	`number`	Vertical spacing between Clips action icons
`clips.spacing.eyebrowToTitleSpacing`	`4`	`number`	Spacing between Clips eyebrow text and title
`clips.spacing.titleToActionSpacing`	`16`	`number`	Horizontal gap between Clips text content and the action icon column
`clips.spacing.titleToCategoriesSpacing`	native layout	`number?`	iOS 11.6.0+ and Android 11.6.3+: Embedded Clips title-to-categories spacing
`clips.spacing.categoriesToMoreSpacing`	native layout	`number?`	iOS 11.6.0+ and Android 11.6.3+: Embedded Clips categories-to-expansion spacing
`clips.spacing.metadataToProgressBarSpacing`	native layout	`number?`	iOS 11.6.0+ and Android 11.6.3+: Embedded Clips metadata-to-progress spacing
`clips.spacing.progressBarToActionSpacing`	native layout	`number?`	iOS 11.6.0+ and Android 11.6.3+: Embedded Clips progress-to-primary-action spacing

Diagram illustrating playerTheme options

Cards#

The cards property applies customizations to Storyteller Cards.

Property	Default Value	Data Type	Description
`audio.mutedIcon`	default icon	`ImageSource?`	Image used for the Cards audio button when audio is muted
`audio.unmutedIcon`	default icon	`ImageSource?`	Image used for the Cards audio button when audio is unmuted

Buttons#

The buttons property applies customizations to buttons which appear throughout the SDK.

Property	Default Value	Data Type	Description
`backgroundColor`	inherits `colors.white.primary`	`ARGB string`	The background color of buttons throughout the SDK
`textColor`	inherits `colors.black.primary`	`ARGB string`	The text color of buttons throughout the SDK
`textCase`	`default`	`TextCase`	Sets the text case for buttons throughout the SDK. Possible values are `upper`, `lower` and `default`
`cornerRadius`	inherits `primitives.cornerRadius`	`number`	The corner radius for all buttons throughout the SDK

Instructions#

Use the instructions property to customize the appearance of the instructions screen.

Property	Default Value	Data Type	Description
`show`	`true`	`boolean`	Determines whether the Instructions Screen is shown the first time a user opens the Story Player. Set to `false` to completely disable the instructions screen.
`headingColor`	inherits `colors.black.primary` for `light`, `colors.white.primary` for `dark`	`ARGB string`	The color of the heading text on the Instructions Screen
`headingTextCase`	`default`	`TextCase`	Determines the text case of the heading on the Instructions Screen. Possible values are `upper`, `lower` and `default`
`headingFont`	`null`	`FontProvider`	Defines the font of the heading text on the Instructions Screen
`subHeadingColor`	inherits `colors.black.secondary` for `light`, `colors.white.secondary` for `dark`	`ARGB string`	The color of the subheading text on the Instructions Screen
`backgroundColor`	inherits `colors.white.primary` for `light`, `colors.black.primary` for `dark`	`ARGB string`	The color of the background of the Instructions Screen
`icons`	`custom`	`null`	A set of custom icons to be used for each instruction on the Instructions Screen
`button.backgroundColor`	inherits `colors.black.primary` for `light`, `colors.white.primary` for `dark`	`ARGB string`	The background color of the button used on the Instructions Screen
`button.textColor`	inherits `colors.white.primary` for `light`, `colors.black.primary` for `dark`	`ARGB string`	The text color of the button used on the Instructions Screen

Diagram illustrating instructions options

Engagement Units#

The engagementUnits property can be used to customize properties relating to Polls and Quizzes.

Property	Default Value	Data Type	Description
`poll.answerTextColor`	inherits `colors.black.primary`	`ARGB string`	The text color used for Poll Answers
`poll.percentBarColor`	`#CDD0DC`	`ARGB string`	The background color of the percentage bar in Poll Answers
`poll.selectedAnswerBorderColor`	inherits `colors.white.tertiary`	`ARGB string`	The border color applied to the selected Poll Answer
`poll.answeredMessageTextColor`	inherits `colors.white.tertiary`	`ARGB string`	The color of the vote count shown to users after they select a Poll Answer
`poll.selectedAnswerBorderImage`	`null`	`ImageSource?`	A border image which can be used for the selected Poll Answer. If this is set, `selectedAnswerBorderColor` is used.
`poll.showImageAnswerGradientOverlay`	`true`	`Boolean`	Shows the gradient overlay behind text in image Poll Answers
`triviaQuiz.correctColor`	inherits `colors.success`	`ARGB string`	The color used to show correct answers in Trivia Quizzes
`triviaQuiz.incorrectColor`	inherits `colors.alert`	`ARGB string`	The color used to show incorrect answers in Trivia Quizzes

Diagram illustrating poll options Diagram illustrating quiz options

Search#

The search property applies customizations to the Search component.

iOS 11.6.0 and Android 11.6.3 support complete Search styling for backgrounds, input, filter button, suggestions, no-results content, the Filters sheet and options, and the Apply button. Partial configurations fall back per field.

Property	Default Value	Data Type	Description
`backIcon`	`chevron.backward` system image on iOS, default back icon on Android	`ImageSource?`	Image to be used as a back icon in the Search UI
`heading.font`	inherits `lists.title.font`	`FontProvider`	Defines the styling of the Filters title in the Filter View
`heading.textSize`	inherits `lists.title.textSize`	`number`	Size of the Filter View title
`heading.lineHeight`	inherits `lists.title.lineHeight`	`number`	The line height of the Filter View title
`heading.textCase`	inherits `lists.title.textCase`	`TextCase`	Sets the text case for Filter View title. Possible values are `upper`, `lower` and `default`
`heading.textColor`	inherits `lists.title.textColor`	`ARGB string`	Color of Filter View title
`backgroundColor`	native Search background	`ARGB string?`	iOS 11.6.0+ and Android 11.6.3+: Search screen background
`input.backgroundColor`	native input background	`ARGB string?`	iOS 11.6.0+ and Android 11.6.3+: Search input background
`input.textColor`	native text colour	`ARGB string?`	iOS 11.6.0+ and Android 11.6.3+: entered Search text colour
`input.placeholderTextColor`	native placeholder colour	`ARGB string?`	iOS 11.6.0+ and Android 11.6.3+: placeholder colour
`input.iconColor`	native icon colour	`ARGB string?`	iOS 11.6.0+ and Android 11.6.3+: Search/clear icon colour
`input.cornerRadius`	native radius	`number?`	iOS 11.6.0+ and Android 11.6.3+: input corner radius
`input.textSize` / `input.lineHeight`	native typography	`number?`	iOS 11.6.0+ and Android 11.6.3+: input typography
`filterButton.backgroundColor` / `filterButton.iconColor`	native colours	`ARGB string?`	iOS 11.6.0+ and Android 11.6.3+: Filters icon-button colours
`filterButton.cornerRadius`	native radius	`number?`	iOS 11.6.0+ and Android 11.6.3+: Filters icon-button radius
`suggestions.textColor` / `suggestions.iconColor` / `suggestions.iconBackgroundColor`	native colours	`ARGB string?`	iOS 11.6.0+ and Android 11.6.3+: suggestion-row colours
`suggestions.textSize` / `suggestions.lineHeight`	native typography	`number?`	iOS 11.6.0+ and Android 11.6.3+: suggestion label typography
`noResults.iconColor`	native icon colour	`ARGB string?`	iOS 11.6.0+ and Android 11.6.3+: no-results illustration colour
`noResults.title.` / `noResults.message.`	native typography	`SearchTextThemeType?`	iOS 11.6.0+ and Android 11.6.3+: no-results text colour, size, line height and case
`filters.backgroundColor` / `filters.handleColor`	native colours	`ARGB string?`	iOS 11.6.0+ and Android 11.6.3+: Filters sheet and handle colours
`filters.sectionHeading.*`	native typography	`SearchTextThemeType?`	iOS 11.6.0+ and Android 11.6.3+: section-heading colour, size, line height and case
`filters.option.*`	native option styling	object	iOS 11.6.0+ and Android 11.6.3+: normal/selected backgrounds, text, borders, radius and typography
`filters.applyButton.*`	native button styling	object	iOS 11.6.0+ and Android 11.6.3+: Apply background, text, case and radius

Fonts#

Custom fonts can be used by setting the customFont property. The SDK will load font files for various font weights that will be used.

iOS 11.6.0 and Android 11.6.3 support the optional light (300) font file and the StorytellerFontWeight values light, regular, medium, semiBold, bold, heavy, and black for the Clips typography properties above. If iOS receives no light font name, it falls back to the configured regular font.

Platform Differences:

iOS: Fonts should be defined as their font name (e.g., Comic Sans MS)
Android: Fonts are defined by file name without extension (e.g., Comic_Sans_MS for Comic_Sans_MS.ttf)

For example, if you have a font file Comic_Sans_MS.ttf containing the font Comic Sans MS, then setting it as the regular custom font should look like this:

Android Compatibility Note: The semibold font weight is only supported on Android API level 28+ (Android 9). On API level 27 and below, the bold font is used instead.

    ...
    customFont:  {
        regular: Platform.OS === 'ios' ? `Comic Sans MS` : `Comic_Sans_MS`,
        ...
    }

On Android, custom fonts can be packaged in either of these locations:

android/app/src/main/assets/fonts/ for file-based font loading.
android/app/src/main/res/font/ for Android font resources. This is recommended when the same custom font theme is used across multiple Storyteller lists or re-rendered often, because Android can reuse packaged font resources more efficiently.

When using res/font, define a font-family XML resource and include the matching font files. For example:

android/app/src/main/res/font/montserrat.xml
android/app/src/main/res/font/montserrat_medium.ttf
android/app/src/main/res/font/montserrat_semibold.ttf
android/app/src/main/res/font/montserrat_bold.ttf

The theme can continue to provide the font file names for each weight:

customFont: {
  regular: Platform.OS === 'ios' ? 'Montserrat Medium' : 'Montserrat-Medium',
  medium: Platform.OS === 'ios' ? 'Montserrat Medium' : 'Montserrat-Medium',
  semibold: Platform.OS === 'ios' ? 'Montserrat SemiBold' : 'Montserrat-SemiBold',
  bold: Platform.OS === 'ios' ? 'Montserrat Bold' : 'Montserrat-Bold',
}

On Android, the SDK normalizes common font file names such as Montserrat-Medium or Montserrat-Medium.ttf to find a matching res/font/montserrat.xml font-family resource. If no matching font resource is found, it falls back to file-based loading from assets/fonts.

This applies to both global themes set with StorytellerSdk.setTheme(theme) and per-view themes passed through a Storyteller component's configuration.theme.

Home#

The home property can be used to customize properties related to the Storyteller Home component.

Property	Default Value	Data Type	Description
`headerTitle.font`	`null`	`FontProvider`	The only font that can vary from theme.font, defines the font for the heading
`headerTitle.textSize`	`22`	`number`	Size of the title in section
`headerTitle.lineHeight`	`28`	`number`	The line height of the title on in section
`headerTitle.textCase`	`default`	`TextCase`	Sets the text case for buttons throughout the UI. Possible values are `upper`, `lower` and `default`
`headerTitle.textColor`	`null`	`ARGB string`	Color of heading text in Storyteller Home
`circularTitle.textSize`	`11`	`number`	Size of the circular title in section
`circularTitle.lineHeight`	`13`	`number`	The line height of the circular title on in section
`singletonTitle.textSize`	`22`	`number`	Size of the singleton title in section
`singletonTitle.lineHeight`	`28`	`number`	The line height of the singleton title in section
`gridTitle.textSize`	`16`	`number`	Size of the grid title in section
`gridTitle.lineHeight`	`22`	`number`	The line height of the grid title on in section

Examples#

    const myTheme: Theme = {
    light: {
        colors: {
            primary: '#309c47'
        },
        tiles: {
            title: {
                textSize: 30
            }
        },
        player: {
            showStoryIcon: true,
        },
        engagementUnits: {
            poll: {
                percentBarColor: '#309c47',
            },
        }
    },
    dark: {
        colors: {
            primary: '#acb32e'
        },
        customFont:  {
            regular: Platform.OS === 'ios' ? `Comic Sans MS` : `Comic_Sans_MS`,
            medium: Platform.OS === 'ios' ? `Comic Sans MS` : `Comic_Sans_MS`,
            semibold: Platform.OS === 'ios' ? `Comic Sans MS` : `Comic_Sans_MS_Bold`,
            bold: Platform.OS === 'ios' ? `Comic Sans MS` : `Comic_Sans_MS_Bold`,
            heavy: Platform.OS === 'ios' ? `Comic Sans MS` : `Comic_Sans_MS_Bold`,
            black: Platform.OS === 'ios' ? `Comic Sans MS` : `Comic_Sans_MS_Bold`,
        },
        tiles: {
            title: {
                textSize: 10
            }
        },
        player: {
            showStoryIcon: true,
        },
        engagementUnits: {
            poll: {
                percentBarColor: '#acb32e',
            }
        }
    },
    };

    ...
    <Storyteller
        ...
        theme={myTheme}
    />

Type Reference#

ImageSource#

Properties that accept custom images (such as icons.share, liveChip.image, rectangularTile.unreadIndicator.image) use the ImageSource type, which can be set using any of the following formats:

// Using require for local assets
theme.player.icons.share = require('./assets/share-icon.png');

// Using image source objects with URI
theme.player.icons.share = { uri: 'https://example.com/share-icon.png' };

// Platform-specific images
theme.player.icons.share = Platform.select({
  ios: require('./assets/share-icon-ios.png'),
  android: require('./assets/share-icon-android.png'),
});

PlayerLikeAnimationResource#

PlayerLikeAnimationResource and PlayerLikeAnimationThemeType are exported from the core package for Clips like-button animations:

import type {
  PlayerLikeAnimationResource,
  PlayerLikeAnimationThemeType,
} from '@getstoryteller/react-native-storyteller-sdk';

The resource can be a string or an object with name, iosName, androidResourceName, and bundlePath. The same resource name can be used on both platforms when the iOS app bundle and Android res/raw resource share a file name:

theme.player.icons.like.animation = {
  liked: { name: 'liked_animation' },
  unliked: { name: 'unliked_animation' },
};

On iOS, name is resolved from the app bundle. On Android, name is resolved from the app's res/raw/<name>.json resources. If the resource names differ by platform, provide iosName or androidResourceName:

theme.player.icons.like.animation = {
  liked: {
    iosName: 'liked_animation_ios',
    androidResourceName: 'liked_animation_android',
  },
};

FontProvider#

The FontProvider type is used to specify custom fonts for text elements. See the Fonts section for platform-specific requirements.

TextCase#

An enum that controls text casing:

'default' - Uses the original text casing
'upper' - Transforms text to uppercase
'lower' - Transforms text to lowercase

ElementAlignment#

An enum for controlling element alignment:

'left' - Align to the left
'center' - Center alignment
'right' - Align to the right

ThemeGradient#

An object type for defining color gradients. See the Gradient section for detailed properties.

ARGB String#

Color values are specified as hexadecimal strings in ARGB format:

#RRGGBB - 6-digit format (e.g., #FF0000 for red)
#AARRGGBB - 8-digit format with alpha channel (e.g., #80FF0000 for 50% transparent red)

Both formats are supported. If alpha is omitted, the color is treated as fully opaque.

RN 12 theme additions#

RN 12 exposes these theme overrides on Android native 12.0.0 and iOS native 11.7.0 under light and dark, except where marked Android-only. Omit them to preserve native or remote defaults.

sheets.cornerRadius: non-negative top corner radius in dp (Android) or points (iOS) for SDK-owned sheets. Zero produces square corners.
player.clips.embeddedVideoSizing: StorytellerEmbeddedClipsVideoSizing.legacy or .widthConstrained. Applies only to Embedded Clips; omission inherits remote settings.
tiles.rectangularTile.titleGradient: gradient behind rectangular story-tile titles.
instructions.button.textSize and .lineHeight: Android-only positive values in sp for the Clips Instructions button.
Gradients accept an optional stops array of { color, location } entries on both platforms. Supply at least two entries with finite, non-decreasing locations from 0 to 1. Equal locations are supported. Retain startColor, endColor, startPosition and endPosition for compatibility and malformed-input fallback. Invalid stops fall back to these endpoint colors.

import { GradientPosition, StorytellerEmbeddedClipsVideoSizing } from '@getstoryteller/react-native-storyteller-sdk';

const theme = {
  light: {
    sheets: { cornerRadius: 16 },
    player: { clips: { embeddedVideoSizing: StorytellerEmbeddedClipsVideoSizing.widthConstrained } },
    tiles: { rectangularTile: { titleGradient: {
      startColor: '#00000000', endColor: '#CC000000',
      startPosition: GradientPosition.topCenter, endPosition: GradientPosition.bottomCenter,
      stops: [
        { color: '#00000000', location: 0 },
        { color: '#80000000', location: 0.6 },
        { color: '#CC000000', location: 1 },
      ],
    } } },
  },
};