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.

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.

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`	`null`	`GradientPosition`	The position indicating where the gradient starts.
`endPosition`	`null`	`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#

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
`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

Diagram illustrating playerTheme options

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.
`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.

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`	(iOS only) The only font that can vary from theme.font, defines the styling of the Filters title in the Filter View
`heading.textSize`	inherits `lists.title.textSize`	`number`	(iOS only) Size of the Filter View title
`heading.lineHeight`	inherits `lists.title.lineHeight`	`number`	(iOS only) The line height of the Filter View title
`heading.textCase`	inherits `lists.title.textCase`	`TextCase`	(iOS only) Sets the text case for Filter View title. Possible values are `upper`, `lower` and `default`
`heading.textColor`	inherits `lists.title.textColor`	`ARGB string`	(iOS only) Color of Filter View title

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.

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`,
        ...
    }

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'),
});

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.