📘

This guide is specific to Web SDK 2.0. If you are still using 1.x, you can find documentation [here](https://developer.incode.com/docs/web-sdk-reference). Contact your Incode Representative for upgrade information and check if you are a candidate for this upgrade.

Full rollout to all clients still TBD.

The Signature module captures a handwritten signature on a touch surface or mouse-driven canvas and uploads it to the backend.

Follows a slim variant of the [document-signing pattern](https://developer.incode.com/docs/web-sdk-2-module-patterns#4-document-signing-modules) — there's no document review or consent step, just capture-and-submit. See the patterns page for the shared lifecycle.

## Tag

`<incode-signature>` is a standard Web Component. Importing the UI subpath registers the custom element; importing the CSS applies the module's styles.

```ts
import '@incodetech/web/signature';
import '@incodetech/web/signature/styles.css';
```

## Properties

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `config` | `SignatureConfig` | ❌ | Configuration options |
| `onFinish` | `() => void` | ❌ | Called when the signature is submitted |
| `onError` | `(error: string) => void` | ❌ | Called when an error occurs |

## Configuration

```typescript
type SignatureConfig = {
  type?: string;
  title?: string;
  subTitle?: string;
  sendBase64?: boolean;
  canvasBackgroundColor?: string;
  penStrokeWidth?: number;
  penColor?: string;
  canvasBorderColor?: string;
};
```

| Option | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `string` | ❌ | Backend-side signature type identifier. |
| `title` | `string` | ❌ | Optional header title. Defaults to a translated "Draw your signature" copy. |
| `subTitle` | `string` | ❌ | Optional subtitle. Note the capital T (matches the backend field). |
| `sendBase64` | `boolean` | ❌ | When `true`, upload as base64 JSON (Omni v2). When `false` (default), upload raw `image/jpeg` bytes. |
| `canvasBackgroundColor` | `string` | ❌ | CSS color or `var(--token)` for the drawing area background. |
| `penStrokeWidth` | `number` | ❌ | Maximum stroke width in CSS pixels (passed through to `signature_pad`'s `maxWidth`). |
| `penColor` | `string` | ❌ | Ink color. |
| `canvasBorderColor` | `string` | ❌ | Border color of the drawing surface. |

## State machine

`SignatureState` is a discriminated union over `status`:

| Status | Description |
| --- | --- |
| `idle` | Initial state. |
| `capture` | User is drawing on the canvas. |
| `submitting` | Uploading the captured signature image. |
| `success` | Upload accepted. |
| `finished` | Terminal. |
| `error` | Fatal error. |

## API methods

| Method | Purpose |
| --- | --- |
| `load()` | Start the machine; transitions to `capture`. |
| `setSignatureValid(isValid)` | Update validity (e.g., enabled when the canvas has at least one stroke). |
| `submit(image)` | Submit the signature. `image` is a base64 string or `Blob` per `sendBase64`. |

Plus the universal lifecycle: `subscribe`, `getState`, `reset`, `stop`.