> ## Documentation Index
> Fetch the complete documentation index at: https://developer.verilock.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Embeddable Widget

> Drop-in verification widget for websites -- no backend code required.

The Verilock Widget is a no-code, embeddable component that launches the full verification flow directly on your website. Add a script tag, configure with data attributes, and you're live.

## Installation

Add the Verilock Widget script to your page:

```html theme={null}
<script src="https://cdn.verilock.io/widget/v1/verilock.js" async></script>
```

<Note>
  The script is lightweight (\~18 KB gzipped) and loads asynchronously. It has no external dependencies.
</Note>

## Display Modes

The widget supports three display modes:

| Mode     | Description                                 | Best For                            |
| -------- | ------------------------------------------- | ----------------------------------- |
| `modal`  | Opens in a centered overlay with a backdrop | Most websites, CTAs                 |
| `inline` | Renders directly inside a container element | Embedded flows, single-page apps    |
| `popup`  | Opens in a new browser window               | Situations where modals are blocked |

## Quick Start: Auto-Init with Data Attributes

The simplest integration uses HTML data attributes with no JavaScript required:

### Modal Mode

```html theme={null}
<button
  data-verilock="trigger"
  data-verilock-key="your_publishable_key"
  data-verilock-mode="modal"
  data-verilock-redirect="https://yourapp.com/verified"
>
  Verify Identity
</button>

<script src="https://cdn.verilock.io/widget/v1/verilock.js" async></script>
```

### Inline Mode

```html theme={null}
<div
  data-verilock="container"
  data-verilock-key="your_publishable_key"
  data-verilock-mode="inline"
  data-verilock-redirect="https://yourapp.com/verified"
  style="width: 100%; max-width: 480px; height: 600px;"
></div>

<script src="https://cdn.verilock.io/widget/v1/verilock.js" async></script>
```

### Popup Mode

```html theme={null}
<button
  data-verilock="trigger"
  data-verilock-key="your_publishable_key"
  data-verilock-mode="popup"
  data-verilock-redirect="https://yourapp.com/verified"
>
  Verify Identity
</button>

<script src="https://cdn.verilock.io/widget/v1/verilock.js" async></script>
```

## Data Attributes Reference

| Attribute                   | Required | Description                                      |
| --------------------------- | -------- | ------------------------------------------------ |
| `data-verilock`             | Yes      | `trigger` (buttons) or `container` (inline divs) |
| `data-verilock-key`         | Yes      | Your publishable API key (starts with `pk_`)     |
| `data-verilock-mode`        | No       | `modal` (default), `inline`, or `popup`          |
| `data-verilock-redirect`    | No       | URL to redirect after completion                 |
| `data-verilock-external-id` | No       | Your internal user ID to attach to the session   |
| `data-verilock-locale`      | No       | Language code: `en`, `es`, `fr`, `de`, `pt`      |
| `data-verilock-theme`       | No       | `light` (default), `dark`, or `auto`             |
| `data-verilock-steps`       | No       | Comma-separated steps: `document,selfie,address` |

## JavaScript API

For full control, initialize the widget programmatically:

```javascript theme={null}
const widget = Verilock.create({
  key: 'your_publishable_key',
  mode: 'modal',
  locale: 'en',
  theme: 'dark',
  externalId: 'user_12345',
  steps: ['document', 'selfie'],
  redirectUrl: 'https://yourapp.com/verified',
});

// Open the widget
widget.open();

// Close the widget
widget.close();

// Destroy the widget and clean up
widget.destroy();
```

### Configuration Options

| Option        | Type            | Default                  | Description                                              |
| ------------- | --------------- | ------------------------ | -------------------------------------------------------- |
| `key`         | string          | --                       | Publishable API key (required)                           |
| `mode`        | string          | `modal`                  | `modal`, `inline`, or `popup`                            |
| `container`   | string\|Element | --                       | CSS selector or DOM element (required for `inline` mode) |
| `locale`      | string          | `en`                     | UI language                                              |
| `theme`       | string          | `light`                  | `light`, `dark`, or `auto`                               |
| `externalId`  | string          | --                       | Your internal user/reference ID                          |
| `steps`       | array           | `['document', 'selfie']` | Verification steps to run                                |
| `redirectUrl` | string          | --                       | Post-completion redirect URL                             |
| `metadata`    | object          | --                       | Custom key-value pairs attached to the session           |

### Inline Mode Example

```html theme={null}
<div id="verilock-container" style="width: 480px; height: 600px;"></div>

<script>
  const widget = Verilock.create({
    key: 'your_publishable_key',
    mode: 'inline',
    container: '#verilock-container',
    theme: 'dark',
    steps: ['document', 'selfie', 'address'],
  });
</script>
```

## Events & Callbacks

Subscribe to lifecycle events to react to verification state changes:

```javascript theme={null}
const widget = Verilock.create({
  key: 'your_publishable_key',
  mode: 'modal',

  onReady: () => {
    console.log('Widget loaded and ready');
  },

  onOpen: () => {
    console.log('Widget opened');
  },

  onClose: () => {
    console.log('Widget closed by user');
  },

  onComplete: (data) => {
    console.log('Verification complete', data.sessionId);
    console.log('Status:', data.status);
    // data.sessionId - The created session ID
    // data.status    - "completed", "approved", "declined"
  },

  onError: (error) => {
    console.error('Widget error', error.code, error.message);
  },

  onStepChange: (step) => {
    console.log('User moved to step:', step.name);
    // step.name  - "document", "selfie", "address", "video"
    // step.index - 0-based step index
  },
});
```

### Event Reference

| Event       | Callback       | Payload                 | Trigger                          |
| ----------- | -------------- | ----------------------- | -------------------------------- |
| Ready       | `onReady`      | --                      | Widget is loaded and initialized |
| Open        | `onOpen`       | --                      | Widget becomes visible           |
| Close       | `onClose`      | --                      | User closes the widget           |
| Complete    | `onComplete`   | `{ sessionId, status }` | Verification flow finished       |
| Error       | `onError`      | `{ code, message }`     | An error occurred                |
| Step Change | `onStepChange` | `{ name, index }`       | User moves to the next step      |

## Full Example

```html theme={null}
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Identity Verification</title>
  <script src="https://cdn.verilock.io/widget/v1/verilock.js" async></script>
</head>
<body>

  <h1>Verify Your Identity</h1>
  <button id="verify-btn">Start Verification</button>
  <p id="status"></p>

  <script>
    document.addEventListener('DOMContentLoaded', () => {
      const statusEl = document.getElementById('status');

      const widget = Verilock.create({
        key: 'pk_live_your_publishable_key',
        mode: 'modal',
        theme: 'auto',
        steps: ['document', 'selfie'],
        metadata: {
          plan: 'premium',
          signup_source: 'website',
        },

        onComplete: (data) => {
          statusEl.textContent = `Verification ${data.status} (${data.sessionId})`;
        },

        onError: (error) => {
          statusEl.textContent = `Error: ${error.message}`;
        },
      });

      document.getElementById('verify-btn').addEventListener('click', () => {
        widget.open();
      });
    });
  </script>

</body>
</html>
```

## Customization

### Theme Overrides

Override default widget styles with CSS custom properties:

```css theme={null}
:root {
  --verilock-primary: #6D28D9;
  --verilock-primary-hover: #5B21B6;
  --verilock-border-radius: 12px;
  --verilock-font-family: 'Inter', sans-serif;
  --verilock-backdrop-color: rgba(0, 0, 0, 0.6);
}
```

### Content Security Policy

If your site uses a Content Security Policy, add the following directives:

```
script-src https://cdn.verilock.io;
frame-src https://verify.verilock.io;
connect-src https://verilock.io;
```

<Warning>
  Use your **publishable key** (`pk_...`) in the widget. Never expose your secret API key in client-side code.
</Warning>