KYC Widget SDK reference

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:

Parameter	Type	Required	Description
`session`	`KycWidgetSession`	Yes	KYC session object obtained from the Create session endpoint
`options`	`KycWidgetOptions`	No	Configuration options for the Widget

Options

type KycWidgetOptions = {
  debug?: boolean;
  layout?: WidgetLayout;
  theme?: WidgetThemeOption;
};

Property	Type	Default	Description
`debug`	`boolean`	`false`	Enable debug mode for additional logging
`layout`	`WidgetLayout`	`'boxed'`	Control how the Widget is laid out on larger viewports. See WidgetLayout for details
`theme`	`WidgetThemeOption`	System preference	Control the visual appearance of the Widget. See WidgetThemeOption for details

layout option: The layout option controls how the Widget is laid out when there is enough room to frame it — on viewports that are both at least md wide (≥768px) and at least 600px tall, i.e. tablets and up. On smaller viewports — narrower or shorter, including phones in landscape — the Widget always fills its container regardless of this option.

'boxed' (default): on viewports that are ≥768px wide and ≥600px tall, centers the Widget and frames its content as a fixed-size card; on smaller viewports it fills its container. Use this when the Widget takes up the whole page (e.g. mounted into a full-page container).
'fluid': renders the Widget so it fills its container, with no frame or centering, so your own container (e.g. a modal or a sized panel) acts as the frame.

Most integrations should rely on the default 'boxed' and only set layout: 'fluid' when embedding the Widget in your own framed container.

const widget = new KycWidget(session, {
  layout: 'fluid'
});

Use 'fluid' when you already provide a centered container or modal around the Widget, to avoid a card-within-a-card appearance on larger viewports.

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

KycWidgetSession

The session object returned by the Create session endpoint.

type KycWidgetSession = {
  url: string;
  token: string;
  data: {
    processes: 'identity' | 'profile' | 'proof-of-address';
  }
};

WidgetLayout

Controls how the Widget is laid out on larger viewports.

type WidgetLayout = 'boxed' | 'fluid';

Value	Description
`'boxed'`	Default. On viewports that are ≥768px wide and ≥600px tall (tablets and up), centers the Widget and frames its content as a fixed-size card; on smaller viewports it fills its container
`'fluid'`	Renders the Widget so it fills its container, with no frame or centering, so your own container acts as the frame

WidgetThemeOption

Controls the visual appearance of the Widget.

type WidgetThemeOption = {
  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 };
  };
};

Property	Type	Description
`appearance`	`'light' \| 'dark'`	Forces light or dark mode, overriding the user’s system preference
`primary`	`ColorTokenValue`	Primary brand color, used for buttons and key interactive elements
`primaryForeground`	`ColorTokenValue`	Text color rendered on top of the primary color
`foreground`	`ColorTokenValue`	Main text color
`emphasisForeground`	`ColorTokenValue`	Emphasized text color
`background`	`ColorTokenValue`	Widget background color
`fontFamily`	`FontFamily`	Font family applied across the Widget. See FontFamily for details
`components`	`object`	Per-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'));

Payment Widget

Travel Rule Widget

KYC Widget

Topper

KYC Widget SDK reference

Constructor

Options

Methods

`mountIframe()`

`unmount()`

`on()`

`off()`

Events

`complete`

`cancel`

`error`

`ready`

Types

KycWidgetSession

WidgetLayout

WidgetThemeOption

ColorTokenValue

FontFamily

Complete usage example

​Constructor

​Options

​Methods

​mountIframe()

​unmount()

​on()

​off()

​Events

​complete

​cancel

​error

​ready

​Types

​KycWidgetSession

​WidgetLayout

​WidgetThemeOption

​ColorTokenValue

​FontFamily

​Complete usage example

Constructor

Options

Methods

`mountIframe()`

`unmount()`

`on()`

`off()`

Events

`complete`

`cancel`

`error`

`ready`

Types

KycWidgetSession

WidgetLayout

WidgetThemeOption

ColorTokenValue

FontFamily

Complete usage example