@zippykyc/react-native

The Zippy KYC Mobile SDK — a complete, drop-in identity verification component for React Native and Expo apps. Renders the full KYC flow (personal info, document capture, selfie, signature, and submission) as a single component, with native camera-permission handling, full theming, and native-feeling chrome built in.

Install

npm install @zippykyc/react-native

yarn add @zippykyc/react-native

This package has no native code of its own — it relies on react-native core (PermissionsAndroid, Linking) for permissions, so it works the same way in a bare React Native app and in an Expo app. There's no config plugin — add the camera usage description yourself:

Expo (managed / prebuild)

In app.json / app.config.js:

{
  "expo": {
    "ios": {
      "infoPlist": {
        "NSCameraUsageDescription": "Camera access is required to capture photos inside the app."
      }
    },
    "android": {
      "permissions": ["android.permission.CAMERA"]
    }
  }
}

Bare React Native

Add NSCameraUsageDescription to Info.plist and android.permission.CAMERA to AndroidManifest.xml by hand.

Quick start

import { KycMobileWebView, type KycCompleteResult } from "@zippykyc/react-native";

export function KycScreen({ inquiryId }: { inquiryId: string }) {
  const handleComplete = (result: KycCompleteResult) => {
    // result: { inquiryId, status: "completed" | "canceled" | "failed", payload? }
    if (result.status === "completed") {
      // navigate to your "verified" screen
    }
  };

  return (
    <KycMobileWebView
      env="staging"
      inquiryId={inquiryId}
      onComplete={handleComplete}
      onCancel={() => {
        // fired when the user taps the SDK's built-in close ("×") button
      }}
    />
  );
}

Environments

Use env="staging" or env="production" — the SDK resolves the correct hosted environment automatically, no setup needed. To point at your own environment (e.g. a local/dev build during development), call configureKycMobileSdk once at app startup, or pass baseUrls directly on the component to override per-instance:

import { configureKycMobileSdk } from "@zippykyc/react-native";

configureKycMobileSdk({
  baseUrls: { staging: "https://your-dev-host/i" },
});

Props

| Prop | Required | Type | Default | Notes | | --- | --- | --- | --- | --- | | env | Yes | "staging" \| "production" | — | Which environment to run against | | inquiryId | Yes | string | — | The verification session/inquiry to run | | onComplete | Yes | (result: KycCompleteResult) => void | — | Fires when the flow reaches a terminal state — { inquiryId, status: "completed" \| "canceled" \| "failed", payload? } | | baseUrls | No | Partial<Record<"staging" \| "production", string>> | — | Per-instance override of the configured environment URLs | | queryParams | No | Record<string, string> | — | Extra parameters to pass along with the session (e.g. an access token) | | colors | No | KycCustomColors | flow's own theme | Rebrand the flow's palette — see Colors | | customCss | No | string | — | Advanced style overrides beyond what colors covers (layout, spacing, alignment) | | onCancel | No | () => void | — | Renders a native close ("×") button and fires this when tapped. Omit entirely and no close button renders | | onBridgeReady | No | () => void | — | Fires once the flow has finished initializing | | onPermissionBlocked | No | (permission: "camera") => void | — | Fires when a permission the flow needs was previously denied ("blocked") — show your own "open Settings" UI | | onBridgeError | No | (error: { code: string; message: string }) => void | — | Fires on any internal bridge failure (e.g. permission lookup error) | | autoOpenSettingsWhenBlocked | No | boolean | false | Automatically open the OS Settings screen when a permission is blocked, instead of just firing onPermissionBlocked | | style | No | StyleProp<ViewStyle> | fills parent | Override the component's default full-fill layout |

Ref methods

const ref = useRef<KycMobileWebViewRef>(null);
<KycMobileWebView ref={ref} ... />

| Method | Description | | --- | --- | | reload() | Reload the flow | | goBack() | Navigate back a step, if the flow supports it | | updateColors(colors) | Re-apply colors without a full reload — useful if your theme can change at runtime | | updateCustomCss(css) | Re-apply customCss without a full reload |

Colors

Pass colors to rebrand the flow to match your app's palette. Anything left unset keeps the flow's own default (shown below):

<KycMobileWebView
  env="staging"
  inquiryId={inquiryId}
  onComplete={handleComplete}
  colors={{
    primary: "#16a34a",
    primaryHover: "#15803d",
    primaryGradientEnd: "#22c55e",
    primarySoft: "#dcfce7",
  }}
/>

| Key | Default | Controls | | --- | --- | --- | | bgStart | #eef2ff | Page background gradient start | | bgEnd | #f8faff | Page background gradient end | | surface | #ffffff | Card / input / dropdown background | | surfaceMuted | #f6f8fb | Secondary surface (secondary buttons, muted rows, notices) | | border | #e2e8f0 | Default border color (inputs, cards, dividers) | | borderFocus | #3f63f3 | Focus outline / focused input border color | | text | #0f172a | Primary text color | | textMuted | #64748b | Secondary/description/hint text color | | primary | #3f63f3 | Primary brand color — buttons, links, active states, progress fill | | primaryHover | #2f4fd1 | Primary button hover color | | primarySoft | #e8edff | Selected-state background, focus ring base | | primaryGradientEnd | #6b84ff | Gradient endpoint paired with primary (buttons, progress bar) | | accent | #3f63f3 | Accent color — used alongside primary in a few places | | accentSoft | #eef2ff | Soft accent background (info icons, notices, hint boxes) | | danger | #dc2626 | Error text/icon color | | dangerSoft | #fee2e2 | Error background color | | success | #059669 | Success text/icon color |

customCss layers on top of colors for anything colors can't cover — both combine automatically, so setting one never drops the other. Call ref.updateColors(colors) / ref.updateCustomCss(css) to change either after the flow has already loaded (setting the prop alone only applies at initial load).

License

MIT