Themes

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.

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

Font

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

Primitives

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

Lists

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

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 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.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 start, center and end
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
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 .end Alignment The elignment of the New Indicator and Live Indicator in Rectangular Tiles. Possible values are start, center or end
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


Player

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


Buttons

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

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


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


Example

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()

PREVIOUS
Forward Arrow