Branding

The branding property lets you customise the player's appearance to match your organisation's brand. For most use cases, setting brandColor1 and brandColor1Text is sufficient.

Quick start

lightbox({
  id: 'YOUR_MODULE_ID',
  branding: {
    colors: {
      brandColor1: 'rgb(186 48 0)',
      brandColor1Text: 'rgb(255 255 255)',
    },
    logo: {
      imageUrl: 'https://example.com/logo.png',
      imageWidth: '200px',
    },
  },
})

Colors

All color values should use CSS color syntax (e.g. rgb(186 48 0), #ba3000).

Brand colors

Property	Description
`brandColor1`	Primary brand color — buttons, highlights, active elements
`brandColor1Text`	Text/icon color on primary brand elements
`brandColor2`	Secondary brand color for secondary themed buttons
`brandColor2Text`	Text/icon color on secondary brand elements
`brandColor3`	Tertiary brand color for tertiary themed buttons
`brandColor3Text`	Text/icon color on tertiary brand elements

Slide content colors

Property	Description
`slideBrandColor1`	Primary color for branded slide elements
`slideBrandColor2`	Secondary color for branded slide elements
`slideBrandColor3`	Tertiary color for branded slide elements

UI element colors

Property	Description
`appBackground`	Application background (mobile/tablet)
`appContentBackground`	Main content area background
`appBoxShadow`	Box shadow for buttons, content area, and overlay boxes
`lightboxBackground`	Desktop lightbox backdrop
`loadingBackground`	Loading state background
`loadingSpinner`	Loading spinner color
`bufferingBackground`	Buffering state background
`bufferingSpinner`	Buffering spinner color
`primaryVideoButtonBackground`	Primary play/pause button background
`primaryVideoButtonIcon`	Primary play/pause button icon
`secondaryVideoButtonBackgroundDesktop`	Secondary button background (desktop)
`secondaryVideoButtonBackgroundMobileTablet`	Secondary button background (mobile/tablet)
`secondaryVideoButtonIcon`	Secondary button icon
`readModeButtonBackground`	Read mode (accessibility) button background
`readModeButtonIcon`	Read mode button icon
`exitButtonBackground`	Exit button background
`exitButtonIcon`	Exit button icon
`keyboardFocus`	Keyboard focus outline color
`scrollbarTrack`	Scrollbar and desktop chapter navigation menu color
`captionsTextColor`	Captions text color
`confetti`	Confetti animation color (opaque colors only)
`textColorDark`	Dark text in the UI
`textColorLight`	Light text in the UI
`uiColorBlack`	The 'black' used in the UI
`uiColorWhite`	The 'white' used in the UI
`uiColorError`	Error state color
`videoAvatarBoxShadow`	Video avatar box shadow
`videoAvatarPlayIcon`	Video avatar play icon

Logo

Display your organisation's logo in the player:

branding: {
  logo: {
    imageUrl: 'https://example.com/logo.png',
    imageWidth: '200px',           // optional, default "200px"
    backgroundColor: 'rgb(255 255 255)', // optional, adds padding
  },
}

Typography

Override the default font stacks. If you use non-system webfonts, ensure they are available on the page where the player appears.

branding: {
  typography: {
    fontStack1: "'Roboto', sans-serif",
    fontStack2: "'Roboto Slab', serif",
    fontUiApp: "'Roboto', sans-serif",
    fontUiSlide: "'Roboto', sans-serif",
    captionsFontWeight: '400',       // '400' or '700'
    chapterMenuFontWeight: '700',
  },
}

Custom fonts

Load custom fonts by providing URLs to the font files:

branding: {
  fonts: [{
    family: 'vcCustomFont',
    regular: 'https://example.com/fonts/CustomFont-Regular.ttf',
    bold: 'https://example.com/fonts/CustomFont-Bold.ttf',
  }],
}

CSS variable overrides

For advanced customisation beyond the typed properties, you can set CSS variables directly. These take precedence over colors and typography for any overlapping values.

branding: {
  cssVariables: [
    { name: '--app-content-background-color', value: 'rgb(245 245 245)' },
  ],
}

Custom CSS

For cases where CSS variables aren't sufficient, inject custom CSS rules targeting specific device layouts. Each rule will automatically have !important appended to ensure highest specificity. Custom CSS only applies to "watch" mode and has no effect on "read" mode.

branding: {
  customCss: [{
    name: 'all',
    value: '.sx-button--theme-video-primary { background-color: rgb(255 0 0); }',
  }],
}

Available device targets: all, desktop, mobile-portrait, mobile-landscape, tablet-portrait, tablet-landscape, tablet-portrait-desktop, tablet-landscape-desktop, mobile-tablet-portrait, mobile-tablet-landscape.

Note that the value string should not contain line break characters. If targeting multiple classes, concatenate them in a single string.