Theming

High-level branding and appearance customization for the React Native Wallet SDK.

The Main Idea

The SDK supports public theme overrides so the wallet experience can better match your host application's brand.

At a high level, you can customize:

• colors
• typography
• spacing
• border radius

You do not need to redefine the full theme. The SDK supports partial theme overrides, so you can change only the values you care about.

Most Common Pattern

The most common approach is to apply theme overrides through VECUProvider so the theme applies across the wallet experience.

<VECUProvider
  config={{
    authToken,
    deploymentStage: 'sandbox',
    theme: {
      colors: {
        primary: '#D4A034',
        primaryForeground: '#1F2937',
      },
    },
  }}
>
  <WalletScreen />
</VECUProvider>

What Most Teams Customize

External client teams usually start with:

• primary
• primaryForeground
• background and surface colors
• text colors

Some teams also customize:

• font family
• font sizes
• spacing scale
• border radius

Most Visible Theme Values

If you are deciding where to start, these are the theme values users will notice first:

• primary: main button color and key call-to-action surfaces
• primaryForeground: text and icon color shown on primary-colored buttons and surfaces
• background: screen background color
• surface: card and container background color
• textPrimary: main body text color
• textSecondary: supporting text and label color

The SDK already provides default values for all of these. You only need to override the ones you want to change.

Component-Level Overrides

If needed, some components also support theme overrides directly.

For example:

<WalletHub
  theme={{
    colors: {
      primary: '#F5C346',
      primaryForeground: '#1F2937',
    },
  }}
/>

NFC and BLE components also accept a theme prop:

<NfcVerifierView
  theme={{
    colors: {
      primary: '#0066CC',
      primaryForeground: '#FFFFFF',
    },
  }}
  onCompleted={handleCompleted}
  onCancel={handleCancel}
/>

Use component-level overrides when you want a specific wallet surface to look slightly different from the app-wide default.

Example Theme Directions

Brand Color Update

theme: {
  colors: {
    primary: '#0066CC',
    primaryForeground: '#FFFFFF',
  },
}

Softer Neutral Surface

theme: {
  colors: {
    background: '#FAFAF8',
    surface: '#FFFFFF',
    border: '#E7E2D8',
  },
}

Rounded Visual Style

theme: {
  borderRadius: {
    sm: 6,
    md: 10,
    lg: 14,
  },
}

Extended Color Tokens

In addition to the core colors above, the SDK exposes additional tokens for finer-grained control over navigation bars, screen backgrounds, and subtle UI elements:

• navBackground — navigation bar and header background
• screenBackground — full-screen background behind cards
• heroCard — primary hero card background
• textOnDark — text rendered on dark or colored surfaces
• textSubtle — de-emphasised labels and supporting text
• textTertiary — tertiary text, metadata, and timestamps
• vinLabel — VIN identifier label color
• statusUnknown — status badge color for unknown or indeterminate states
• shadow — shadow and elevation tint color
• placeholder — placeholder text in inputs

These tokens have sensible defaults and only need to be set if your host app's design requires them.

Accessibility

When customizing colors, keep button and text contrast readable.

In particular:

• primary and primaryForeground should maintain strong contrast
• body text should remain easy to read against the chosen background
• status and error colors should remain visually distinct

Recommendation

Start with a small theme override first, confirm the wallet experience still looks clear and readable on device, and then expand customization only if your application needs it.

Related Guidance

• Quick Start for the minimum integration path
• Configuration for provider setup
• Components for the default VECUProvider and WalletHub usage pattern