Custom 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 storytellerRowView = new Storyteller.StorytellerStoriesRowView(
  'storyteller-row-view'
);
const myRowTheme = new Storyteller.UiTheme();
storytellerRowView.theme = myRowTheme;

Learn more

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`	`#1A1A1A`	`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
`focusIndicator`	`colors.primary`	`string` - CSS color property	Used for the focus outlines of interactive elements

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 (external) space between each Story Tile in a row
`row.startInset`	`12`	`number`	The (external) space before the first Story Tile in a row
`row.endInset`	`12`
`row.startPadding`	`0`	`number`	The (internal) space before the first Story Tile in a row
`row.endPadding`	`0`	`number`	The (internal) space after the last Story Tile in a row
`row.showScrollIndicator`	`true`	`boolean`	Whether the scroll indicator should be visible on non-touch screens (it's always hidden on touch screens)
`row.scrollIndicatorBackgroundColor`	`white`	`string` - CSS color property	The background color of the scroll indicator
`row.scrollIndicatorColor`	`rgba(26, 26, 26, 0.7)`	`string` - CSS color property	The color of the scroll indicator icon. Ignored if `scrollIndicatorIcon` is set
`row.scrollIndicatorIcon`	`null`	`<img>` URL property	URL of a custom scroll indicator icon. Passing in a HTML string is not supported.
`row.scrollIndicatorFade`	`true`	`boolean`	Used to show/hide the fade overlay on the edges of the Story row
`row.scrollIndicatorInlineAlignment`	`inside`	`inside`, `outside`	Whether the scroll arrows should appear on top of the row (`inside`) or next to it (`outside`).
`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
`chip.show`	`true`	`boolean`	Used to show/hide the new/live chip
`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.liveChip.readImage`	`null`	`string` - `<img>` `src` property	Image to be used in place of default read Live Indicator for circular tiles
`circularTile.liveChip.unreadImage`	`null`	`string` - `<img>` `src` property	Image to be used in place of default unread Live Indicator for circular tiles
`circularTile.liveChip.readBackgroundColor`	inherits `colors.black.tertiary`	`string` - CSS color property	Background color of the circular tiles Live Indicator when all Pages have been read
`circularTile.liveChip.unreadBackgroundColor`	inherits `colors.alert`	`string` - CSS color property	Background color of the circular tiles Live Indicator when the Story contains unread Pages
`circularTile.liveChip.readTextColor`	inherits `colors.white.primary`	`string` - CSS color property	Text color of the circular tiles Live Indicator when all Pages have been read
`circularTile.liveChip.unreadTextColor`	inherits `colors.white.primary`	`string` - CSS color property	Text color of the circular tiles Live Indicator when the Story contains unread Pages
`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 is 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 or linear-gradient	The color of the ring around a circular tile when the Story is unread
`circularTile.readIndicatorColor`	`#C5C5C5`	`string` - CSS color property or linear-gradient	The color of the ring around a circular tile when the Story is read
`circularTile.unreadStrokeWidth`	`2`	`number` (in px)	The thickness of the ring around a circular tile when the Story is unread
`circularTile.readStrokeWidth`	`1`	`number` (in px)	The thickness of the ring around a circular tile when the Story is read
`circularTile.scrollIndicatorBlockAlignment`	`cell`	`cell`, `thumbnail`	Whether the scroll arrows should be centered with the whole cell (including the titles), or with the thumbnail.
`rectangularTile.liveChip.readImage`	`null`	`string` - `<img>` `src` property	Image to be used in place of default read Live Indicator for rectangular tiles
`rectangularTile.liveChip.unreadImage`	`null`	`string` - `<img>` `src` property	Image to be used in place of default unread Live Indicator for rectangular tiles
`rectangularTile.liveChip.readBackgroundColor`	inherits `colors.black.tertiary`	`string` - CSS color property	Background color of the rectangular tiles Live Indicator when all Story Pages have been read or the Clip has been viewed
`rectangularTile.liveChip.unreadBackgroundColor`	inherits `colors.alert`	`string` - CSS color property	Background color of the rectangular tiles Live Indicator when the Story contains unread Pages or the Clip has not been viewed
`rectangularTile.liveChip.readTextColor`	inherits `colors.white.primary`	`string` - CSS color property	Text color of the rectangular tiles Live Indicator when all Story Pages have been read or the Clip has been viewed
`rectangularTile.liveChip.unreadTextColor`	inherits `colors.white.primary`	`string` - CSS color property	Text color of the rectangular tiles Live Indicator when the Story contains unread Pages or the Clip has not been viewed
`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
`rectangularTile.unreadIndicator.showWebStoriesIcon`	`false`	`boolean`	Set this to true to show a story icon on rectangular thumbnails
`rectangularTile.showGradient`	`true`	`boolean`	Set this to `false` to hide the gradient behind the story title on rectangular cells

Diagram illustrating rowTheme options

Diagram illustrating Live Tile options

Player#

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

Property	Default Value	Data Type	Description
`disableUrls`	`false`	`Bool`	Disable the hash URLs when opening a Story. Note that this will also disable sharing.
`showStoryIcon`	`true`	`Bool`	Shows the Story icon in the Player
`showShareButton`	`true`	`Bool`	Shows the share button in the Player. Setting this to `false` entirely disables sharing in Storyteller
`actionButton.icon`	`null`	`<img>` URL property	URL of a 20x20px custom icon to display in the action buttons. Passing in a HTML string is not supported.
`actionButton.showOnMobile`	`true`	`Bool`	Shows the action button on top of the player on small screens. If set to `false`, the action button will only be shown if there is sufficient space to display it underneath the player.
`actionButton.alignment`	`center`	`ButtonAlignment`	Sets the alignment of the action button on small screens. Possible values are `left`, `center` and `right`. If there is enough space for the button to sit underneath the player, it will always be centered.
`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

Diagram illustrating playerTheme options

Clip Player#

The clipPlayer property is used to customize properties relating to the Clip Player.

Property	Default Value	Data Type	Description
`disableUrls`	`false`	`Bool`	Disable the hash URLs when opening a Clip. Note that this will also disable sharing.
`showShareButton`	`true`	`Bool`	Shows the share button in the Player. Setting this to `false` entirely disables sharing.
`showLikeButton`	`true`	`Bool`	Shows the like button in the Player.

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",
  swipe: "./icon-swipe-custom.png",
}

theme.instructions.icons = customIcons

Diagram illustrating instructionsTheme 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`	`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

Diagram illustrating pollTheme options

Diagram illustrating quizTheme options

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';