Developers  /  Web SDK  /  Custom Themes

        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
        NEXT
        Working with UsersForward Arrow