Skip to main content
Complete reference documentation for the @uphold/enterprise-kyc-widget-web-sdk package. The main class for creating and managing KYC Widget instances is KycWidget. It requires a KycWidgetSession object that must be created through the API before instantiating the Widget.

​
Constructor

new KycWidget(
  session: KycWidgetSession,
  options?: KycWidgetOptions
)
Parameters:
ParameterTypeRequiredDescription
sessionKycWidgetSessionYesKYC session object obtained from the Create session endpoint
optionsKycWidgetOptionsNoConfiguration options for the Widget

​
Options

type KycWidgetOptions = {
  debug?: boolean;
  theme?: KycTheme;
};
PropertyTypeDefaultDescription
debugbooleanfalseEnable debug mode for additional logging
themeKycThemeSystem preferenceControl the visual appearance of the Widget. See KycTheme for details
theme option: The theme option lets you control the visual appearance of the Widget. By default, the Widget automatically detects and matches the user’s browser or OS appearance preference (light or dark). Use this option when you want to enforce a specific theme regardless of the user’s system settings. 
const widget = new KycWidget(session, {
  theme: {
    appearance: 'dark',
    primary: { light: '#6200EA', dark: '#BB86FC' },
    // Alternatively, a single color string applies to both appearances, e.g. primary: '#6200EA'
    // primary: '#6200EA',
    fontFamily: 'Inter, sans-serif',
    components: {
      button: { borderRadius: '8px' }
    }
  }
});

​
Methods

​
mountIframe()

Mounts the KYC Widget iframe to the specified DOM element. Parameters:
  • element: The HTML element where the Widget should be mounted
Example: 
// Ensure the container has appropriate sizing
const container = document.getElementById('kyc-container');

widget.mountIframe(container);
The container element should have explicit dimensions set via CSS. The Widget will fill the entire container. Minimum recommended size is 400px width × 600px height for optimal user experience.

​
unmount()

Unmounts and cleans up the KYC Widget iframe. Example: 
widget.unmount();
The Widget will not unmount itself when a flow is finished, either by successful completion, user cancellation, or unrecoverable error, so it must always be called manually.

​
on()

Registers an event listener for Widget events. Parameters:
  • event: The event name to listen for
  • callback: Function to execute when the event is triggered
Example: 
widget.on('complete', () => {
  console.log('KYC completed');
});

​
off()

Removes an event listener for KYC Widget events. Parameters:
  • event: The event name to stop listening for
  • callback: The specific function to remove (must be the same reference as used in on())
Example: 
const handleComplete = () => {
  console.log('KYC completed');
};

// Register the listener
widget.on('complete', handleComplete);

// Remove the listener
widget.off('complete', handleComplete);

​
Events

The KYC Widget emits several events during its lifecycle that you can listen to using the on() method.

​
complete

Fired when all KYC processes have been submitted. 
type KycWidgetCompleteEvent = {
  detail: {};
};
Example: 
widget.on('complete', () => {
  console.log('KYC processes submitted');

  widget.unmount();
});
The complete event signals submission, not approval. Final verification outcomes are delivered asynchronously via KYC webhooks. Monitor those server-side to update your user’s status.

​
cancel

Fired when the user cancels the KYC flow. 
type KycWidgetCancelEvent = {
  detail: {};
};
Example: 
widget.on('cancel', () => {
  console.log('KYC cancelled by user');

  widget.unmount();
});

​
error

Fired when an unrecoverable error occurs during the KYC flow. 
type KycWidgetErrorEvent = {
  detail: {
    error: string;
  };
};
Example: 
widget.on('error', (event) => {
  console.error('KYC error:', event.detail.error);

  widget.unmount();
});

​
ready

Fired when the KYC Widget has finished loading. 
type KycWidgetReadyEvent = {
  detail: {};
};
Example: 
widget.on('ready', () => {
  console.log('KYC Widget is ready');
});

​
Types

​
KycWidgetProcess

The set of KYC processes supported by the Widget. 
type KycWidgetProcess = 'identity' | 'proof-of-address';
ValueDescription
identityIdentity verification process
proof-of-addressProof of address verification process

​
KycWidgetSession

The session object returned by the Create session endpoint. 
type KycWidgetSession = {
  url: string;
  token: string;
  data: {
    processes: KycWidgetProcess[];
  }
};

​
KycTheme

Controls the visual appearance of the Widget. 
type KycTheme = {
  appearance?: 'light' | 'dark';
  primary?: ColorTokenValue;
  primaryForeground?: ColorTokenValue;
  foreground?: ColorTokenValue;
  emphasisForeground?: ColorTokenValue;
  background?: ColorTokenValue;
  fontFamily?: FontFamily;
  components?: {
    button?: { borderRadius?: string };
    input?: { borderRadius?: string };
    card?: { borderRadius?: string };
  };
};
PropertyTypeDescription
appearance'light' | 'dark'Forces light or dark mode, overriding the user’s system preference
primaryColorTokenValuePrimary brand color, used for buttons and key interactive elements
primaryForegroundColorTokenValueText color rendered on top of the primary color
foregroundColorTokenValueMain text color
emphasisForegroundColorTokenValueEmphasized text color
backgroundColorTokenValueWidget background color
fontFamilyFontFamilyFont family applied across the Widget. See FontFamily for details
componentsobjectPer-component style overrides for button, input, and card (each accepts borderRadius?: string)

​
ColorTokenValue

A color value that can be a single string applied to both light and dark modes, or separate values per mode. 
type ColorTokenValue = string | { light: string; dark: string };

​
FontFamily

A font family that can be a single string applied to all slots, or separate values per slot (mono, sans, serif). 
type FontFamily = string | Partial<Record<'mono' | 'sans' | 'serif', string>>;

​
Complete usage example

Here’s an end-to-end example showing how to use the KYC Widget with all events: 
import { KycWidget } from '@uphold/enterprise-kyc-widget-web-sdk';

// Create a KYC Widget session from your backend
const session = await createKycWidgetSession();

// Initialize the Widget
const widget = new KycWidget(session, {
  debug: true
});

// Handle ready event
widget.on('ready', () => {
  console.log('KYC Widget is ready');
});

// Handle completion (monitor final outcomes via webhooks)
widget.on('complete', () => {
  console.log('KYC processes submitted');
  widget.unmount();
});

// Handle cancellation
widget.on('cancel', () => {
  console.log('KYC cancelled by user');
  widget.unmount();
});

// Handle errors
widget.on('error', (event) => {
  console.error('KYC error:', event.detail.error);
  widget.unmount();
});

// Mount the Widget's iframe to a DOM element
widget.mountIframe(document.getElementById('kyc-container'));