# Signature Module

<WebSDK2 />

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](doc: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`.

## See also

* [Module: Electronic Signature](doc:web-sdk-2-module-electronic-signature): multi-document PDF flow with consent checkboxes
* [Module Patterns → document-signing](doc:web-sdk-2-module-patterns#4-document-signing-modules)
* [Individual Modules](doc:web-sdk-2-individual-modules)