Themes

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

const myTheme = new Storyteller.UiTheme();
Storyteller.sharedInstance.theme = myTheme;

This object is used as the global theme for every StorytellerListView included in your site.

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

const myRowTheme = new Storyteller.UiTheme();
storytellerRowView.theme = myRowTheme;

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

Configuring a UiTheme

A UiTheme consists of the following properties:

  • light sets the Theme to apply for light mode
  • dark sets the Theme to apply for dark mode

Which property is used depends on the uiStyle property of the StorytellerListView.

Creating Themes

The Theme object contains all of the properties which can be customized in the SDK.

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 string - CSS color property The default accent color used throughout the UI. In general, this should be the primary brand color.
success #3BB327 string - CSS color property Used to indicate correct answers in Quizzes.
alert #E21219 string - CSS color property Used to indicate incorrect answers in Quizzes.
white.primary #FFFFFF string - CSS color property Used for white text
white.secondary white.primary at 85% opacity string - CSS color property Used for light text
white.tertiary white.primary at 70% opacity string - CSS color property Used for gray text
black.primary #000000 string - CSS color property Used for black text
black.secondary black.primary at 85% opacity string - CSS color property Used for light black text
black.tertiary black.primary at 70% opacity string - CSS color property Used for gray text

Font

Use the font property to set a custom font for use throughout the SDK. This should be set as a CSS font-family property. The default value is inherit.

Primitives

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

Property Default Value Data Type Description
cornerRadius 4 number The corner radius in pixels 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
lists.backgroundColor inherits colors.white.primary for light, colors.black.primary for dark string - CSS color property Required for outline on Live chip and fade to the side of the row on the Web SDK.
row.tileSpacing 8 number The space between each Story Tile in a row
row.startInset 12 number The space before the first Story Tile in a row
row.endInset 12 number The space after the last Story Tile in a row
row.scrollIndicatorBackgroundColor white string - CSS color property The background color of the scroll indicator
row.scrollIndicatorIconColor #1A1A1A string - CSS color property The color of the scroll indicator icon. Ignored if scrollIndicatorIcon is set
row.scrollIndicatorIcon null string - <img> url property Url of a custom scroll indicator icon
row.scrollIndicatorFade true boolean Used to show/hide the fade overlay on the edges of the story row
hideStoryTitle false boolean Used to hide the story tile titles (only applies to round tiles)
grid.tileSpacing 8 number The space between each Story 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

Story Tiles

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

Property Default Value Data Type Description
chip.textSize 11 number Text size for the New Indicator and Live Indicator
liveChip.readImage null string - <img> src property Image to be used in place of default read Live Indicator
liveChip.unreadImage null string - <img> src property Image to be used in place of default unread Live Indicator
liveChip.unreadBackgroundColor inherits colors.alert string - CSS color property Background color of the Live Indicator when the story contains unread pages
liveChip.readBackgroundColor inherits colors.black.tertiary string - CSS color property Background color of the Live Indicator when all pages have been read
liveChip.textColor inherits colors.white.primary string - CSS color property Text color of the Live Indicator
title.textSize 11 number Size of the Story Title on a Tile
title.lineHeight 13 number The line height of the Story Title on a Tile
title.alignment center Alignment The alignment of the Story Title on a Tile. Possible values are start, center and end
circularTile.title.unreadTextColor inherits colors.black.primary for light, colors.white.primary for dark string - CSS color property The text color of the Story Title for a circular tile when the story unread
circularTile.title.readTextColor inherits colors.black.tertiary for light, colors.white.tertiary for dark string - CSS color property The text color of the Story Tile for a circular tile when the story is read
circularTile.unreadIndicatorColor inherits colors.primary string - CSS color property The color of the ring around a circular tile when the story is unread
circularTile.readIndicatorColor #C5C5C5 string - CSS color property The color of the ring around a circular tile when the story is read
rectangularTile.title.textColor inherits colors.white.primary string - CSS color property The text color of the Story Title for a rectangular tile
rectangularTile.padding 8 number The internal padding for a rectangular story tile
rectangularTile.chip.alignment end Alignment Alignment of the New Indicator and Live Indicator in Rectangular Tiles, can be start, center or end.
rectangularTile.unreadIndicator.image null string - <img> src property An image which can be used in place of the default unread indicator for a rectangular tile
rectangularTile.unreadIndicator.backgroundColor inherits colors.primary string - CSS color property The background color of the unread indicator for a rectangular tile
rectangularTile.unreadIndicator.textColor inherits colors.white.primary string - CSS color property The text color of the unread indicator for a rectangular tile


Player

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

Property Default Value Data Type Description
showStoryTitle true Bool Shows the Story Title in the Player
showShareButton true Bool Shows the share button in the Player. Setting this to false entirely disables sharing in Storyteller
icons.share null string - image url or data string An image to be used in place of the default share icon
playAllStories false boolean Set this to true to stop the player from closing after all unread stories have been viewed


Buttons

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

Property Default Value Data Type Description
backgroundColor inherits colors.white.primary string - CSS color property The background color of buttons throughout the SDK
textColor inherits colors.black.primary string - CSS color property The text color of buttons throughout the SDK
textCase default TextCasing 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 Bool 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 string - CSS color property The color of the heading text on the Instructions Screen
subHeadingColor inherits colors.black.secondary for light, colors.white.secondary for dark string - CSS color property The color of the subheading text on the Instructions Screen
backgroundColor inherits colors.white.primary for light, colors.black.primary for dark string - CSS color property The color of the background of the Instructions Screen
icons null InstructionsIcons 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 string - CSS color property The background color of the button used on the Instructions Screen
button.textColor inherits colors.white.primary for light, colors.black.primary for dark string - CSS color property The text color of the button used on the Instructions Screen

The icons property can be used to provide a completely custom set of icons. The icons should be 48x48 PNGs. An example of using this property is shown below:

    const customIcons: {
      forward: "./icon-forward-custom.png",
      pause: "./icon-pause-custom.png",
      back: "./icon-back-custom.png",
      move: "./icon-move-custom.png",
    }

    theme.instructions.icons = customIcons


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 string - CSS color property The text color used for Poll Answers
poll.percentBarColor #CDD0DC string - CSS color property The background color of the percentage bar in Poll Answers
poll.selectedAnswerBorderColor inherits colors.white.tertiary string - CSS color property The border color applied to the selected Poll Answer
poll.answeredMessageTextColor inherits colors.white.tertiary string - CSS color property The color of the vote count shown to users after they select a Poll Answer
poll.selectedAnswerBorderImage null UIImage? A border image which can be used for the selected Poll Answer. If this is set, selectedAnswerBorderColor is used
poll.showVoteCount true Bool Shows the approximate number of Poll Answers after a user selects an answer. If this is set to false, the message "Thanks for voting!" is displayed instead
poll.showPercentBarBackground false Bool Adds a striped background under the percentage bar in Poll Answers
triviaQuiz.correctColor inherits colors.success string - CSS color property The color used to show correct answers in Trivia Quizzes
triviaQuiz.incorrectColor inherits colors.alert string - CSS color property The color used to show incorrect answers in Trivia Quizzes


Example

const theme = new Storyteller.UiTheme({
  light: {
    colors: {
      primary: 'blue',
      secondary: 'green',
    },
  },
});

// Setting theme by direct property access
theme.light.colors.primary = 'red';

// Applying light/dark mode specific values
theme.light.instructions.headingColor = 'black';
theme.dark.instructions.headingColor = 'white';
PREVIOUS
Forward Arrow