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.RowView("storyteller-row-view");
const myRowTheme = new Storyteller.UiTheme();
storytellerRowView.theme = myRowTheme;
For more information on setting a theme on an individual list, see StorytellerListView.
A UiTheme
consists of the following properties:
light
sets the Theme
to apply for light modedark
sets the Theme
to apply for dark modeWhich property is used depends on the uiStyle
property of the StorytellerListView.
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.
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 |
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
.
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 |
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.scrollIndicatorColor |
#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 |
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 |
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 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 |
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 |
rectangularTile.unreadIndicator.showWebStoriesIcon |
false |
boolean |
Set this to true to show a story icon on rectangular thumbnails |
The player
property is used to customize properties relating to the Story Player.
Property | Default Value | Data Type | Description |
---|---|---|---|
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 |
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 |
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 |
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
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 |
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';