Asset Overrides

Replace the SDK's built-in branded illustrations (SVG) and animations (Lottie) with your own artwork - no fork, no rebuild. Overrides are supplied at runtime through the same setup() / web-component config channels you already use for the rest of the SDK.

This is a different mechanism from Theming & Styling: CSS tokens recolor functional UI chrome (buttons, inputs, the spinner track) via currentColor, while asset overrides replace whole decorative illustrations and animations — tutorial graphics, success/fail screens, and similar branding moments.

Quick start

Pass assets and/or animations maps to the uiConfig option of setup(). Keys are type-checked — only allowlisted keys autocomplete, and an unknown key is a compile error:

import { setup } from '@incodetech/web';

await setup({
  apiURL: API_URL,
  token: session.token,
  uiConfig: {
    assets: {
      // A plain string is treated as a URL (or raw `<svg …>` markup if it starts with '<')
      'faceMatch.success': 'https://cdn.example.com/id/match-ok.svg',
    },
    animations: {
      'id.tutorial.front': { url: 'https://cdn.example.com/id/tutorial.json' },
    },
  },
});

Every SDK instance on the page picks up these overrides. To change overrides after setup() has already run, call setUiConfig directly:

import { setUiConfig } from '@incodetech/web';

setUiConfig({
  assets: { 'faceMatch.success': 'https://cdn.example.com/id/match-ok.svg' },
});

setUiConfig replaces the entire UiConfig object rather than merging into it — pass every field you want to keep (logoSrc, assets, animations, and so on) each time you call it.

How overrides resolve

An override wins in this order, most specific first:

1. Per-instance — the assets / animations maps on a single web component's config prop (see Per-instance overrides below).
2. Global — the assets / animations maps passed to setup({ uiConfig }) or setUiConfig.
3. Built-in default — the SDK's own illustration or animation, unchanged.

If a key has no override at any tier, the SDK renders exactly what it renders today. A malformed override, a { url } that fails to load, or an unknown key all fall back to the built-in default silently — an override never throws and never blocks rendering.

What can be overridden

Overrides are allowlist-only. Only the keys listed below can be overridden; there is no override-by-path or wildcard. Every other SDK graphic — functional icons, form-control glyphs, and capture-critical overlays like camera frames or alignment guides — stays fixed. Recolor those through CSS tokens instead.

SVG illustrations (AssetKey)

Lottie animations (AnimationKey)

Only assets that are purely decorative or branding graphics are on this list. If a key you need isn't here, it's most likely functional chrome or a capture-critical overlay, and isn't a candidate for override.

Override forms

SVG overrides

AssetOverride accepts several shapes, so you can pick whichever is least work:

type AssetOverride =
  | string // a URL, or raw `<svg …>` markup (detected by a leading '<')
  | { url: string } // fetched and rendered via <img>; no script execution
  | { raw: string } // inline markup, sanitized before injection
  | { svg: SvgComponent }; // a precompiled Preact component (build-time integrations)

{ raw } markup is sanitized before it's injected into the page — scripts, event-handler attributes, <foreignObject>, and external href / xlink:href references are stripped (in-document #fragment references used for gradients and filters are preserved). If sanitizing strips everything, the SDK treats the override as failed and falls back to the built-in default.

Animation overrides

type AnimationOverride =
  | LottieAnimationData // a parsed Lottie JSON object
  | { url: string } // fetched and cached at runtime
  | { animationData: LottieAnimationData };

An animation { url } is fetched once and cached; a failed fetch falls back to the built-in default.

Per-instance overrides

Every module web component's config prop also accepts assets and animations. This overrides the global setup({ uiConfig }) values for that one element only — useful when a single flow instance on the page needs different branding than the rest of the app:

const el = document.createElement('incode-selfie');
el.manager = selfieManager;
el.config = {
  token,
  assets: {
    'videoSelfie.success': 'https://cdn.example.com/id/selfie-done.svg',
  },
};
container.appendChild(el);

<incode-flow> takes the same two maps on its FlowConfig:

flow.config = {
  token: session.token,
  animations: {
    'loader.spinner': { url: 'https://cdn.example.com/id/spinner.json' },
  },
};

If the same key is set both globally and per-instance, the per-instance value wins for that element.

The loading spinner

The default loading spinner (shown during flow initialization, module loading, and transitions) is CSS + inline SVG, not an asset — it stays fully customizable through the --spinner-* CSS tokens described in Theming & Styling, unaffected by this feature.

loader.spinner is a separate, optional override that replaces the built-in spinner entirely with your own SVG or Lottie asset. Set it (as an AssetOverride for an SVG, or an AnimationOverride for a Lottie animation) and the SDK renders your asset instead of the CSS spinner everywhere the spinner appears. Leave it unset and the CSS spinner renders exactly as it does today.

Accessibility & security

• Accessible names and aria-hidden always come from the SDK's built-in catalog, never from your override. Replacing an asset's pixels can't remove its accessible name.
• The WCAG 2.2.2 five-second auto-stop on animations can't be bypassed by an override. A customer-supplied Lottie animation is still subject to the same auto-stop as the built-in default.
• Raw SVG markup is sanitized before injection (see Override forms above). Prefer { url } when you control the hosting and don't need inline theming.
• The SDK never recolors a customer-supplied asset. Color the asset yourself before handing it to the SDK.

TypeScript

import type {
  AssetKey,
  AssetOverride,
  AssetOverrides,
  AnimationKey,
  AnimationOverride,
  AnimationOverrides,
  SvgComponent,
} from '@incodetech/web';

The same types are also available from @incodetech/web/extensibility if you're already importing shared components/hooks from that subpath.

See Also

• Theming & Styling: CSS-token recoloring of UI chrome
• IncodeFlow Component: full FlowConfig reference, including assets / animations
• Web Components: setting per-instance config on any module element
• TypeScript Types: the full type catalog