Skip to main content

iOS - Access Theme Colors

note

Modules that inherit from Q2ModuleBase or directly conform to the Module interface receive moduleDataSource, which exposes the active ThemeProvider.

Quick Start​

Follow these three steps in any module:

  1. Access moduleDataSource.
  2. Request a color using theme?.color(forKey:).
  3. Apply .uiColor to your UIKit UI element.
Quick Start Example
let primaryTextColor = moduleDataSource?.theme?.color(forKey: "mobColorTextPrimary").uiColor
let accentColor = moduleDataSource?.theme?.color(forKey: "mobColorButtonPrimary").uiColor

titleLabel.textColor = primaryTextColor
ctaButton.tintColor = accentColor

Implementation​

Q2ModuleBase already provides moduleDataSource, so you can use theme colors directly.

Q2ModuleBase Example
import Q2ModuleInterfaces
import UIKit

final class PartnerUIModule: Q2ModuleBase {
    private let titleLabel = UILabel()
    private let subtitleLabel = UILabel()

    override func didOpen(_ identifier: String) {
        titleLabel.textColor = moduleDataSource?.theme?.color(forKey: "mobColorTextPrimary").uiColor
        subtitleLabel.textColor = moduleDataSource?.theme?.color(forKey: "mobColorTextSecondary").uiColor
    }
}

SwiftUI Usage​

If your module UI is built with SwiftUI, request the theme color the same way and bridge it to SwiftUI Color.

SwiftUI Example
import Q2ModuleInterfaces
import SwiftUI

struct PartnerView: View {
    let moduleDataSource: ModuleDataSource?

    var body: some View {
        if let uiColor = moduleDataSource?.theme?.color(forKey: "mobColorTextPrimary").uiColor {
            Text("Account Summary")
                .foregroundColor(Color(uiColor))
        } else {
            Text("Account Summary")
        }
    }
}

Guidance​

  • Use theme colors for all module UI elements to stay consistent with Q2MobileApp.
  • Reuse the same color keys for the same semantic meaning (primary text, secondary text, primary action).
  • If a key does not resolve at runtime, current iOS behavior returns .clear; validate key names carefully.

Key Resolution​

When your module calls:

let uiColor = moduleDataSource?.theme?.color(forKey: "your-key").uiColor

the key is resolved against the active merged theme dictionary in this order:

  1. constants
  2. palettevars
  3. themevars

If the same key exists in multiple sections, later sections override earlier sections, so themevars has the highest priority.

Key Source​

Use this baseline file to discover valid key names during development:

  • Q2DevApp/conf/default-theme.json
tip

default-theme.json is a baseline sample. Runtime values can differ by FI theme, environment, and custom theme overrides.

Theme Source Lifecycle​

Color keys are not always resolved only from the bundled default-theme.json. In Q2MobileApp, theme data can come from multiple sources depending on app state:

  1. Bundled default theme
    • On startup, the app can use the bundled conf/default-theme.json as a baseline.
  2. Last successful downloaded theme
    • If a theme was previously downloaded, that cached theme can be used instead of the baseline.
  3. Current active server theme
    • When a new theme is selected and downloaded, it becomes the active source for key resolution.