The appearance of the SDK can be customized by setting the theme
property. This requires a UiTheme
configurable object.
let myTheme = UiTheme()
Storyteller.theme = myTheme
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 (for example, in the didFinishLaunchingWithOptions
callback in the AppDelegate
).
It is also possible to apply a specific theme to a specific StorytellerListView instance. For example:
let myRowTheme = 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 mode.dark
- sets the Theme
to apply for dark mode.Which 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 |
UIColor |
The default accent color used throughout the UI. In general, this should be the primary brand color. |
success |
#3BB327 |
UIColor |
Used to indicate correct answers in Quizzes. |
alert |
#E21219 |
UIColor |
Used to indicate incorrect answers in Quizzes. |
white.primary |
#FFFFFF |
UIColor |
Used for white text |
white.secondary |
white.primary at 85% opacity |
UIColor |
Used for light text |
white.tertiary |
white.primary at 70% opacity |
UIColor |
Used for gray text |
black.primary |
#000000 |
UIColor |
Used for black text |
black.secondary |
black.primary at 85% opacity |
UIColor |
Used for light black text |
black.tertiary |
black.primary at 70% opacity |
UIColor |
Used for gray text |
Use the font
property to set a custom font for use throughout the SDK
To set this create an instance of a class which implements the FontProvider
protocol and provides an instance of UIFont
for the various weights. For example:
private var customFont: FontProvider {
class CustomFont: FontProvider {
override func font(weight: StorytellerFontWeight, size: CGFloat) -> UIFont? {
switch weight {
case .regular, .medium:
return UIFont(name: "MyCustomFont", size: size)
case .semibold, .bold, .heavy, .black:
return UIFont(name: "MyCustomFontBold", size: size)
default:
return UIFont(name: "MyCustomFont", size: size)
}
}
}
return CustomFont()
}
theme.font = customFont
The primitives
object contains base values which are used throughout the SDK.
Property | Default Value | Data Type | Description |
---|---|---|---|
cornerRadius |
4 |
CGFloat |
The corner radius 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 |
---|---|---|---|
backgroundColor |
colors.white.primary |
UIColor |
Required for outline on Live chip and fade to the side of the row on the Web SDK |
row.tileSpacing |
8 |
CGFloat |
The space between each Story Tile in a row |
row.startInset |
12 |
CGFloat |
The space before the first Story Tile in a row |
row.endInset |
12 |
CGFloat |
The space after the last Story Tile in a row |
grid.tileSpacing |
8 |
CGFloat |
The space between each Story Tile in a grid, both vertically and horizontally |
grid.columns |
2 |
CGFloat |
The number of columns in a grid |
grid.topInset |
12 |
CGFloat |
The space before the first row in a grid |
grid.bottomInset |
12 |
CGFloat |
The space after the last row in a grid |
home.startInset |
12 |
CGFloat |
Space to the left of Storyteller Home |
home.endInset |
12 |
CGFloat |
Space to the right of Storyteller Home |
home.heading.font |
System Font | CGFloat |
The only font that can vary from theme.font, defines the font for the heading |
home.heading.textColor |
colors.black.primary |
UIColor |
Color of heading text in Storyteller Home |
The storyTiles
property can be used to customize the appearance of the Story Tiles.
Property | Default Value | Data Type | Description |
---|---|---|---|
chip.textSize |
11 |
CGFloat |
Text size for the New Indicator and Live Indicator. |
liveChip.readImage |
null |
UIImage? |
Image to be used in place of default read Live Indicator. |
liveChip.unreadImage |
null |
UIImage? |
Image to be used in place of default unread Live Indicator |
liveChip.unreadBackgroundColor |
colors.alert |
UIColor |
Background color of the Live Indicator when the story contains unread pages. |
liveChip.readBackgroundColor |
colors.black.tertiary |
UIColor |
Background color of the Live Indicator when all pages have been read |
liveChip.textColor |
colors.white.primary |
UIColor |
Text color of the Live Indicator |
title.textSize |
11 |
CGFloat |
Size of the Story Title on a Tile |
title.show |
true |
Bool |
Show or hide the title text in all tiles |
title.lineHeight |
13 |
CGFloat |
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 left , center and right |
circularTile.title.unreadTextColor |
inherits colors.black.primary for light , colors.white.primary for dark |
UIColor |
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 |
UIColor |
The text color of the Story Tile for a circular tile when the story is read |
circularTile.unreadIndicatorColor |
inherits colors.primary |
UIColor |
The color of the ring around a circular tile when the story is unread |
circularTile.readIndicatorColor |
#C5C5C5 |
UIColor |
The color of the ring around a circular tile when the story is read |
circularTile.unreadBorderWidth |
2 |
CGFloat |
The width of Circular Story Tile ring border in unread state |
circularTile.readBorderWidth |
2 |
CGFloat |
The width of Circular Story Tile ring border in read state |
rectangularTile.padding |
8 |
CGFloat |
The internal padding for a rectangular story tile |
rectangularTile.title.textColor |
inherits colors.white.primary |
UIColor |
The text color of the Story Title for a rectangular tile |
rectangularTile.chip.alignment |
right |
Alignment |
The alignment of the New Indicator and Live Indicator in Rectangular Tiles. Possible values are left , center or right |
rectangularTile.unreadIndicator.image |
null |
UIImage? |
An image which can be used in place of the default unread indicator for a rectangular tile |
rectangularTile.unreadIndicator.backgroundColor |
inherits colors.primary |
UIColor |
The background color of the unread indicator for a rectangular tile |
rectangularTile.unreadIndicator.textColor |
inherits colors.white.primary |
UIColor |
The text color of the unread indicator for a rectangular tile |
The player
property is used to customize properties relating to the Story Player.
Property | Default Value | Data Type | Description |
---|---|---|---|
showStoryIcon |
false |
Bool |
Shows the round story icon before the Story Title in the Player |
showTimestamp |
true |
Bool |
Shows the timestamp after the Story Title in the Player, indicating how long ago a story was published |
showShareButton |
true |
Bool |
Shows the share button in the Player. Setting this to false entirely disables sharing in Storyteller |
liveChipImage |
null |
UIImage? |
Image used in place of Live Chip before Live Story Titles |
icons.share |
null |
UIImage? |
An image to be used in place of the default share icon |
icons.refresh |
null |
UIImage? |
Refresh button image to be used in place of refresh share icon, used in the error state |
The buttons
property applies customizations to buttons which appear throughout the SDK.
Property | Default Value | Data Type | Description |
---|---|---|---|
backgroundColor |
inherits colors.white.primary |
UIColor |
The background color of buttons throughout the SDK |
textColor |
inherits colors.black.primary |
UIColor |
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 |
CGFloat |
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 |
UIColor |
The color of the heading text on the Instructions Screen |
subHeadingColor |
inherits colors.black.secondary for light , colors.white.secondary for dark |
UIColor |
The color of the subheading text on the Instructions Screen |
backgroundColor |
inherits colors.white.primary for light , colors.black.primary for dark |
UIColor |
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 |
UIColor |
The background color of the button used on the Instructions Screen |
button.textColor |
inherits colors.white.primary for light , colors.black.primary for dark |
UIColor |
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:
private var customIcons: InstructionsIcons {
InstructionsIcons(
forward: UIImage(named: "icon-forward-custom"),
pause: UIImage(named: "icon-pause-custom"),
back: UIImage(named: "icon-back-custom"),
move: UIImage(named: "icon-move-custom")
)
}
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 |
UIColor |
The text color used for Poll Answers |
poll.percentBarColor |
#CDD0DC |
UIColor |
The background color of the percentage bar in Poll Answers |
poll.selectedAnswerBorderColor |
inherits colors.white.tertiary |
UIColor |
The border color applied to the selected Poll Answer |
poll.answeredMessageTextColor |
inherits colors.white.tertiary |
UIColor |
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 |
UIColor |
The color used to show correct answers in Trivia Quizzes |
triviaQuiz.incorrectColor |
inherits colors.alert |
UIColor |
The color used to show incorrect answers in Trivia Quizzes |
let theme = UITheme()
// Setting theme by direct property access
theme.light.colors.primary = UIColor.blue
// Applying light/dark mode specific values
theme.light.instructions.headingColor = UIColor.black
theme.dark.instructions.headingColor = UIColor.white
// Subclassing resources providers
class CustomFontProvider: FontProvider {
override func font(weight: StorytellerFontWeight, size: CGFloat) -> UIFont? {
switch weight {
case .regular, .medium:
return UIFont(name: "Custom Font Regular", size: size)
case .semibold, .bold, .heavy, .black:
return UIFont(name: "Custom Font Bold", size: size)
default:
return UIFont(name: "Custom Font Regular", size: size)
}
}
}
theme.row.fonts = CustomFontProvider()
let icons = InstructionIcons(
forward: UIImage(named: "custom-icon-forward-white"),
pause: UIImage(named: "custom-icon-pause-white"),
back: UIImage(named: "custom-icon-forward-white").
move: UIImage(named: "custom-icon-move-white")
)
theme.dark.instructions.icons = CustomIconsProviderWhite()