@smileid/web-sdk

Instructions

These components can be used to capture id document or liveness images

1. smart-camera-web
2. document-capture-screens
3. selfie-capture-screens
4. user-details
5. consent

user-details

<smileid-user-details> is a standalone, product-agnostic form that collects the end user's name and a contact method (email and/or phone). It is used by the v3 SmartSelfie flow when the partner config omits user_details, and can be mounted by any product without pulling in the selfie/smart-camera-web bundle.

import '@smileid/web-sdk/user-details';

<smileid-user-details theme-color="#001096"></smileid-user-details>

Attributes

• theme-color — primary colour of the Continue button (default #001096).
• hide-attribution — "true" to hide the "Powered by Smile ID" footer.

Event

• smileid-user-details.submitted — dispatched on window when the user submits a valid form. event.detail is { given_names, last_name, email?, phone_number? } (at least one of email/phone_number; phone normalized to E.164). The payload type is exported as UserDetailsPayload.

consent

<smileid-consent> is a standalone, product-agnostic, region-aware consent screen. It is shown by v3 product flows (SmartSelfie, DocV, Biometric KYC, …) when the partner config omits a granted consent_information, and can be mounted by any product without pulling in the selfie/smart-camera-web bundle.

import '@smileid/web-sdk/consent';

<smileid-consent
  theme-color="#001096"
  partner-name="Acme"
  policy-url="https://acme.example/privacy"
  consent-region="eu"
></smileid-consent>

Attributes

• theme-color — primary colour of the Allow button (default #001096).
• hide-attribution — "true" to hide the "Powered by Smile ID" footer.
• partner-name — partner name interpolated into the notice copy.
• partner-logo — partner logo URL shown in the header lockup.
• policy-url — partner privacy-policy URL linked from "Learn more".
• consent-region — "eu" starts the checkbox un-ticked and blocks Allow until ticked (regulated regions); "non-eu" may start pre-ticked; any other value (or none) auto-detects from the browser's locale/timezone, defaulting to the compliance-safe "eu" behaviour when ambiguous. The initial checkbox state is read on first render, so set consent-region before inserting the element into the DOM.

Events

• smileid-consent.granted — dispatched on window when the user grants consent. event.detail is { granted: true, granted_at } (granted_at is an ISO 8601 timestamp). Consumers enrich this into the full v3 consent part by adding notice_language and notice_privacy_policy_url from their own config. The detail type is exported as ConsentGrantedDetail.
• smileid-consent.denied — dispatched on window when the user declines.

Localization

The web components support multiple languages and string customization through the localisation module.

Quick Start

import { setCurrentLocale, getDirection } from '@smileid/web-sdk/localisation';

// Set language (supports 'en-GB', 'fr-FR', 'ar-EG')
await setCurrentLocale('fr-FR');

// Apply RTL direction for Arabic
document.documentElement.dir = getDirection();

Customizing Strings

Override specific UI text:

await setCurrentLocale('en-GB', {
  locales: {
    'en-GB': {
      selfie: {
        instructions: {
          title: 'Verify your identity with a selfie',
        },
      },
    },
  },
});

Adding Custom Languages

Register a new language:

import {
  registerLocale,
  setCurrentLocale,
} from '@smileid/web-sdk/localisation';

registerLocale('sw-KE', {
  direction: 'ltr',
  common: {
    back: 'Rudi',
    continue: 'Endelea',
    // ... all required keys
  },
});

await setCurrentLocale('sw-KE');

Full Localization Guide - Complete documentation including available languages, all translation keys, and custom language setup.

Orchestration

To build your own flow, we have several components that can be used together.

document-capture-instructions

This is the screen used to instruct the user how to capture document using both the camera and/or upload.