Themes#

The appearance of the SDK can be customized using the StorytellerTheme class. This class allows you to configure the visual appearance of all Storyteller content in your app.

final theme = StorytellerTheme(
  light: ThemeType(
    colors: ThemeColors(primary: '#1C62EB'),
  ),
);

await Storyteller.setTheme(theme);

Set the theme as early as possible in your application's lifecycle (for example, in your main() function after initializing the SDK).

It is also possible to apply a specific theme to an individual StorytellerListView instance or when opening content. For example:

final rowTheme = StorytellerTheme(
  light: ThemeType(
    colors: ThemeColors(primary: '#FF0000'),
  ),
);

// Apply to a list view
StorytellerStoriesRowView(
  categories: ['news'],
  theme: rowTheme,
);

// Apply when opening a collection
await Storyteller.openCollection(
  'collection-id',
  theme: rowTheme,
);

For more information on setting a theme on an individual list, see StorytellerListViews.

Configuring a StorytellerTheme#

A StorytellerTheme consists of the following properties:

light - sets the ThemeType to apply for light mode.
dark - sets the ThemeType to apply for dark mode.

Which property is used depends on the device's current appearance mode.

Creating Themes#

The ThemeType 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 primary color to #FF0000 will also result in the New Indicator for Rectangular Tiles being colored red. Such properties are indicated in the tables 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`	The default accent color used throughout the UI. In general, this should be the primary brand color. Color strings should be in hex format (e.g., `#1C62EB`).
`success`	`#3BB327`	`String`	Used to indicate correct answers in Quizzes.
`alert`	`#E21219`	`String`	Used to indicate incorrect answers in Quizzes.
`white.primary`	`#FFFFFF`	`String`	Used for white text
`white.secondary`	`white.primary` at 85% opacity	`String`	Used for light text
`white.tertiary`	`white.primary` at 70% opacity	`String`	Used for gray text
`black.primary`	`#000000`	`String`	Used for black text
`black.secondary`	`black.primary` at 85% opacity	`String`	Used for light black text
`black.tertiary`	`black.primary` at 70% opacity	`String`	Used for gray text

Example:

ThemeColors(
  primary: '#1C62EB',
  success: '#3BB327',
  alert: '#E21219',
  white: ThemeTextColors(
    primary: '#FFFFFF',
    secondary: '#D9D9D9',
    tertiary: '#B3B3B3',
  ),
  black: ThemeTextColors(
    primary: '#000000',
    secondary: '#D9D9D9',
    tertiary: '#B3B3B3',
  ),
)

Font#

Use the customFont property to set a custom font for use throughout the UI.

To set this, create an instance of ThemeCustomFont and provide font family names for various weights:

ThemeCustomFont(
  regular: 'MyCustomFont-Regular',
  medium: 'MyCustomFont-Medium',
  semibold: 'MyCustomFont-SemiBold',
  bold: 'MyCustomFont-Bold',
  heavy: 'MyCustomFont-Heavy',
  black: 'MyCustomFont-Black',
)

Make sure the fonts are properly registered in your app's pubspec.yaml:

flutter:
  fonts:
    - family: MyCustomFont-Regular
      fonts:
        - asset: fonts/MyCustomFont-Regular.ttf
    - family: MyCustomFont-Bold
      fonts:
        - asset: fonts/MyCustomFont-Bold.ttf
    # ... other weights

Primitives#

The primitives object contains base values which are used throughout the UI.

Property	Default Value	Data Type	Description
`cornerRadius`	`8`	`double`	The corner radius used for rectangular tiles, buttons and poll/quiz answers

Example:

ThemePrimitives(
  cornerRadius: 12.0,
)

Lists#

The lists property customizes properties of the various list types available from the SDK.

Property	Default Value	Data Type	Description
`backgroundColor`	`colors.white.primary`	`String`	Required for outline on Live chip and fade to the side of the row
`enablePlayerOpen`	`true`	`bool`	Controls whether the SDK opens the player when a tile is tapped. When set to `false`, the SDK will not open the player and the app must handle tile taps via the `onTileTapped` callback.
`animateTilesOnReorder`	`true`	`bool`	When the `reloadData()` method is called to update lists, a reorder animation is added to visualize the updating process.
`row.tileSpacing`	`8`	`double`	The space between each Tile in a row
`row.startInset`	`12`	`double`	The space before the first Tile in a row
`row.endInset`	`12`	`double`	The space after the last Tile in a row
`grid.tileSpacing`	`8`	`double`	The space between each Tile in a grid, both vertically and horizontally
`grid.columns`	`2`	`int`	The number of columns in a grid.
`grid.topInset`	`12`	`double`	The space before the first row in a grid
`grid.bottomInset`	`12`	`double`	The space after the last row in a grid
`title.font`	`null`	`ThemeCustomFont`	Defines the font of the Title in Section
`title.textSize`	`22`	`double`	Size of the Title in Section
`title.lineHeight`	`28`	`double`	The line height of the Title in Section
`title.textCase`	`default`	`String`	Sets the text case for the Title in Section. Possible values are `upper`, `lower` and `default`
`title.textColor`	`null`	`String`	Color of Title in Section

Example:

ThemeLists(
  backgroundColor: '#FFFFFF',
  enablePlayerOpen: true,
  animateTilesOnReorder: true,
  row: ThemeListRow(
    tileSpacing: 8.0,
    startInset: 12.0,
    endInset: 12.0,
  ),
  grid: ThemeListGrid(
    tileSpacing: 8.0,
    columns: 2,
    topInset: 12.0,
    bottomInset: 12.0,
  ),
  title: ThemeTitle(
    textSize: 22.0,
    lineHeight: 28.0,
    textCase: 'default',
    textColor: '#000000',
  ),
)

Gradient#

The ThemeGradient class allows for the creation of a color gradient, with options to customize both the colors and the positions at which the gradient starts and ends.

Property	Default Value	Data Type	Description
`startColor`	required	`String`	The color where the gradient begins (hex format).
`endColor`	required	`String`	The color where the gradient ends (hex format).
`startPosition`	required	`int`	The position indicating where the gradient starts (0-8).
`endPosition`	required	`int`	The position indicating where the gradient ends (0-8).

Gradient Positions#

Gradient positions are represented as integers from 0-8:

Value	Position
`0`	Bottom left corner
`1`	Bottom center edge
`2`	Bottom right corner
`3`	Center left edge
`4`	Center
`5`	Center right edge
`6`	Top left corner
`7`	Top center edge
`8`	Top right corner

Example:

ThemeGradient(
  startColor: '#FF0000',
  endColor: '#0000FF',
  startPosition: 6, // Top left
  endPosition: 2,   // Bottom right
)

Tiles#

The tiles property can be used to customize the appearance of the Tiles.

Property	Default Value	Data Type	Description
`chip.textSize`	`11`	`double`	Text size for the New Indicator and Live Indicator.
`chip.show`	`true`	`bool`	Used to show/hide the new/live chip
`title.textSize`	`11`	`double`	Size of the Title on a Tile
`title.lineHeight`	`13`	`double`	The line height of the Title on a Tile
`title.alignment`	`center`	`String`	The alignment of the 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`	`String`	The text color of the Title for a circular tile when the story or the clip is unread
`circularTile.title.readTextColor`	inherits `colors.black.tertiary` for `light`, `colors.white.tertiary` for `dark`	`String`	The text color of the Tile for a circular tile when the story or the clip is read
`circularTile.unreadIndicatorColor`	inherits `colors.primary`	`String`	The color of the ring around a circular tile when the story or the clip is unread
`circularTile.readIndicatorColor`	`#C5C5C5`	`String`	The color of the ring around a circular tile when the story or the clip is read
`circularTile.unreadIndicatorGradient`	`null`	`ThemeGradient`	The gradient of the ring around a circular tile when the story or the clip is unread. If set, overrides `circularTile.unreadIndicatorColor`
`circularTile.unreadIndicatorBorderColor`	`null`	`String`	The border color of the ring around a circular tile when the story or the clip is unread
`circularTile.readIndicatorBorderColor`	`null`	`String`	The border color of the ring around a circular tile when the story or the clip is read
`circularTile.unreadBorderWidth`	`2`	`double`	The width of Circular Tile ring border in unread state
`circularTile.readBorderWidth`	`2`	`double`	The width of Circular Tile ring border in read state
`circularTile.liveChip.readImage`	`null`	`ThemeImage`	Image to be used in place of default read Live Indicator.
`circularTile.liveChip.unreadImage`	`null`	`ThemeImage`	Image to be used in place of default unread Live Indicator
`circularTile.liveChip.unreadBackgroundColor`	`colors.alert`	`String`	Background color of the Live Indicator when the story contains unread pages or the clip has not been viewed.
`circularTile.liveChip.readBackgroundColor`	`colors.black.tertiary`	`String`	Background color of the Live Indicator when all story pages have been read or the clip has been viewed.
`circularTile.liveChip.unreadBackgroundGradient`	`null`	`ThemeGradient`	The gradient of the ring around a live tile and background of the Live Indicator. If set, overrides `circularTile.liveChip.unreadBackgroundColor`
`circularTile.liveChip.unreadTextColor`	`colors.white.primary`	`String`	Text color of the Live Indicator when the story contains unread pages or the clip has not been viewed.
`circularTile.liveChip.readTextColor`	`colors.white.primary`	`String`	Text color of the Live Indicator when all story pages have been read or the clip has been viewed.
`circularTile.liveChip.unreadBorderColor`	`null`	`String`	Border color of the Live Indicator when the story contains unread pages or the clip has not been viewed.
`circularTile.liveChip.readBorderColor`	`null`	`String`	Border color of the Live Indicator when all story pages have been read or the clip has been viewed.
`rectangularTile.padding`	`8`	`double`	The internal padding for a rectangular story or the clip tile
`rectangularTile.title.textColor`	inherits `colors.white.primary`	`String`	The text color of the Title for a rectangular tile
`rectangularTile.chip.alignment`	`right`	`String`	The alignment of the New Indicator and Live Indicator in Rectangular Tiles. Possible values are `left`, `center` or `right`
`rectangularTile.unreadIndicator.image`	`null`	`ThemeImage`	An image which can be used in place of the default unread indicator for a rectangular tile. If set, overrides `rectangularTile.unreadIndicator.gradient`
`rectangularTile.unreadIndicator.gradient`	`null`	`ThemeGradient`	The background gradient of the unread indicator for a rectangular tile. If set, overrides `rectangularTile.unreadIndicator.backgroundColor`
`rectangularTile.unreadIndicator.backgroundColor`	inherits `colors.primary`	`String`	The background color of the unread indicator for a rectangular tile
`rectangularTile.unreadIndicator.textColor`	inherits `colors.white.primary`	`String`	The text color of the unread indicator for a rectangular tile
`rectangularTile.unreadIndicator.borderColor`	`null`	`String`	Border color of the unread indicator for a rectangular tile
`rectangularTile.liveChip.readImage`	`null`	`ThemeImage`	Image to be used in place of default read Live Indicator.
`rectangularTile.liveChip.unreadImage`	`null`	`ThemeImage`	Image to be used in place of default unread Live Indicator. If set, overrides `rectangularTile.liveChip.unreadBackgroundGradient`
`rectangularTile.liveChip.unreadBackgroundGradient`	`null`	`ThemeGradient`	Gradient background to be used for the Live Indicator. If set, overrides `rectangularTile.liveChip.unreadBackgroundColor`
`rectangularTile.liveChip.unreadBackgroundColor`	`colors.alert`	`String`	Background color of the Live Indicator when the story contains unread pages or the clip has not been viewed.
`rectangularTile.liveChip.readBackgroundColor`	`colors.black.tertiary`	`String`	Background color of the Live Indicator when all pages have been read or the clip has been viewed
`rectangularTile.liveChip.unreadTextColor`	`colors.white.primary`	`String`	Text color of the Live Indicator when the story contains unread pages or the clip has not been viewed.
`rectangularTile.liveChip.readTextColor`	`colors.white.primary`	`String`	Text color of the Live Indicator when all story pages have been read or the clip has been viewed.
`rectangularTile.liveChip.unreadBorderColor`	`null`	`String`	Border color of the Live Indicator when the story contains unread pages or the clip has not been viewed.
`rectangularTile.liveChip.readBorderColor`	`null`	`String`	Border color of the Live Indicator when all story pages have been read or the clip has been viewed.

Diagram illustrating rowTheme rectangular options

Diagram illustrating rowTheme circular options

Example:

ThemeTiles(
  chip: ThemeTileChip(
    textSize: 11.0,
    show: true,
  ),
  title: ThemeTileTitle(
    textSize: 11.0,
    lineHeight: 13.0,
    alignment: 'center',
  ),
  circularTile: ThemeCircularTile(
    unreadIndicatorColor: '#1C62EB',
    readIndicatorColor: '#C5C5C5',
    unreadBorderWidth: 2.0,
    readBorderWidth: 2.0,
  ),
  rectangularTile: ThemeRectangularTile(
    padding: 8.0,
    title: ThemeRectangularTileTitle(
      textColor: '#FFFFFF',
    ),
  ),
)

Player#

The player property is used to customize properties relating to the Story and Clips 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
`showLikeButton`	`true`	`bool`	Shows the like button in the Clips Player. Setting this to `false` entirely disables liking in Storyteller
`liveChip.image`	`null`	`ThemeImage`	Image used in place of Live Chip before Live Story or Clip Titles. If set, it overrides `liveChip.backgroundGradient`
`liveChip.textColor`	`null`	`String`	Text color used for badge label for Live Story or Clip
`liveChip.backgroundGradient`	`null`	`ThemeGradient`	Background gradient of the badge for Live Story or Clip. If set, it overrides `liveChip.backgroundColor`
`liveChip.backgroundColor`	`theme.colors.alert`	`String`	Background color of the badge for Live Story or Clip
`liveChip.borderColor`	`null`	`String`	Border color of the badge for Live Story or Clip
`icons.share`	`null`	`ThemeImage`	An image to be used in place of the default share icon
`icons.refresh`	`null`	`ThemeImage`	Refresh button image to be used in place of refresh share icon, used in the error state
`icons.likeInitial`	`null`	`ThemeImage`	An image to be used in place of the default like icon when the clip is not liked
`icons.likeLiked`	`null`	`ThemeImage`	An image to be used in place of the default like icon when the clip is liked

Diagram illustrating playerTheme options

Example:

ThemePlayer(
  showStoryIcon: false,
  showTimestamp: true,
  showShareButton: true,
  showLikeButton: true,
  icons: ThemePlayerIcons(
    share: ThemeImage(filePath: 'assets/icons/share.png'),
    likeInitial: ThemeImage(filePath: 'assets/icons/like.png'),
    likeLiked: ThemeImage(filePath: 'assets/icons/like_filled.png'),
  ),
)

Buttons#

The buttons property applies customizations to buttons which appear throughout the UI.

Property	Default Value	Data Type	Description
`backgroundColor`	inherits `colors.white.primary`	`String`	The background color of buttons throughout the UI
`textColor`	inherits `colors.black.primary`	`String`	The text color of buttons throughout the SDK
`textCase`	`default`	`String`	Sets the text case for buttons throughout the UI. Possible values are `upper`, `lower` and `default`
`cornerRadius`	inherits `primitives.cornerRadius`	`double`	The corner radius for all buttons throughout the UI

Example:

ThemeButtons(
  backgroundColor: '#000000',
  textColor: '#FFFFFF',
  textCase: 'upper',
  cornerRadius: 8.0,
)

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`	The color of the heading text on the Instructions Screen
`headingTextCase`	`default`	`String`	Determines the text case of the heading on the Instructions Screen. Possible values are `upper`, `lower` and `default`
`headingFont`	`null`	`ThemeCustomFont`	Defines the font of the heading text on the Instructions Screen
`subHeadingColor`	inherits `colors.black.secondary` for `light`, `colors.white.secondary` for `dark`	`String`	The color of the subheading text on the Instructions Screen
`backgroundColor`	inherits `colors.white.primary` for `light`, `colors.black.primary` for `dark`	`String`	The color of the background of the Instructions Screen
`icons`	`null`	`ThemeInstructionIcons`	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`	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`	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 or appropriate asset images. An example of using this property is shown below:

ThemeInstructionIcons(
  forward: ThemeImage(filePath: 'assets/icons/forward.png'),
  pause: ThemeImage(filePath: 'assets/icons/pause.png'),
  back: ThemeImage(filePath: 'assets/icons/back.png'),
  move: ThemeImage(filePath: 'assets/icons/move.png'),
)

Diagram illustrating instructionsTheme options

Example:

ThemeInstructions(
  show: true,
  headingColor: '#000000',
  headingTextCase: 'default',
  subHeadingColor: '#666666',
  backgroundColor: '#FFFFFF',
  button: ThemeInstructionButton(
    backgroundColor: '#000000',
    textColor: '#FFFFFF',
  ),
)

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`	The text color used for Poll Answers
`poll.percentBarColor`	`#CDD0DC`	`String`	The background color of the percentage bar in Poll Answers
`poll.selectedAnswerBorderColor`	inherits `colors.primary`	`String`	The border color applied to the selected Poll Answer
`poll.answeredMessageTextColor`	inherits `colors.white.tertiary`	`String`	The color of the vote count shown to users after they select a Poll Answer
`poll.selectedAnswerBorderImage`	`null`	`ThemeImage`	A border image which can be used for the selected Poll Answer. If this is set, `selectedAnswerBorderColor` is used.
`triviaQuiz.correctColor`	inherits `colors.success`	`String`	The color used to show correct answers in Trivia Quizzes
`triviaQuiz.incorrectColor`	inherits `colors.alert`	`String`	The color used to show incorrect answers in Trivia Quizzes

Diagram illustrating pollTheme options

Diagram illustrating quizTheme options

Example:

ThemeEngagementUnits(
  poll: ThemePoll(
    answerTextColor: '#000000',
    percentBarColor: '#CDD0DC',
    selectedAnswerBorderColor: '#1C62EB',
  ),
  triviaQuiz: ThemeTriviaQuiz(
    correctColor: '#3BB327',
    incorrectColor: '#E21219',
  ),
)

Search#

The search property applies customizations to the Search component.

Property	Default Value	Data Type	Description
`backIcon`	default back icon	`ThemeImage`	Image to be used as a back icon in the Search UI
`heading.font`	inherits `lists.title.font`	`ThemeCustomFont`	Defines the styling of the Filters title in the Filter View
`heading.textSize`	inherits `lists.title.textSize`	`double`	Size of the Filter View title
`heading.lineHeight`	inherits `lists.title.lineHeight`	`double`	The line height of the Filter View title
`heading.textCase`	inherits `lists.title.textCase`	`String`	Sets the text case for Filter View title. Possible values are `upper`, `lower` and `default`
`heading.textColor`	inherits `lists.title.textColor`	`String`	Color of Filter View title

Example:

ThemeSearch(
  backIcon: ThemeImage(filePath: 'assets/icons/back.png'),
  heading: ThemeTitle(
    textSize: 22.0,
    lineHeight: 28.0,
    textCase: 'default',
    textColor: '#000000',
  ),
)

Home#

The home property can be used to customize properties related to the Storyteller Home component.

Property	Default Value	Data Type	Description
`headerTitle.font`	`null`	`ThemeCustomFont`	Defines the font for the heading
`headerTitle.textSize`	`22`	`double`	Size of the title in section
`headerTitle.lineHeight`	`28`	`double`	The line height of the title in section
`headerTitle.textCase`	`default`	`String`	Sets the text case for the title. Possible values are `upper`, `lower` and `default`
`headerTitle.textColor`	`null`	`String`	Color of heading text in Storyteller Home
`circularTitle.textSize`	`11`	`double`	Size of the circular title in section
`circularTitle.lineHeight`	`13`	`double`	The line height of the circular title in section
`singletonTitle.textSize`	`22`	`double`	Size of the singleton title in section
`singletonTitle.lineHeight`	`28`	`double`	The line height of the singleton title in section
`gridTitle.textSize`	`16`	`double`	Size of the grid title in section
`gridTitle.lineHeight`	`22`	`double`	The line height of the grid title in section

Example:

ThemeHome(
  headerTitle: ThemeTitle(
    textSize: 22.0,
    lineHeight: 28.0,
    textCase: 'default',
    textColor: '#000000',
  ),
  circularTitle: ThemeHomeTitle(
    textSize: 11.0,
    lineHeight: 13.0,
  ),
)