> For the complete documentation index, see [llms.txt](https://docs.avonnicomponents.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avonnicomponents.com/lwc-components/core-components/signature-pad.md).
# Signature Pad
`avonni-signature-pad`
A canvas that lets users draw and capture a handwritten signature.
## Overview
**Signature Pad** is a Lightning Web Component that lets users draw a signature or freehand sketch on a canvas and capture it as a Base64 PNG.
Use it in your own Lightning Web Components to collect authorizations, acknowledgements, or annotations. You control the pen color and size, drawing mode, background, toolbar layout, and which toolbar buttons appear—all through the component's attributes—and read the result from the `change` event.
### Use Cases
* **Authorizations:** Capture a customer signature to approve a transaction.
* **Acknowledgements:** Record sign-off on terms or delivery receipts.
* **Field service:** Collect on-site sign-offs on a tablet.
* **Annotations:** Let users sketch or mark up freehand.
* **Forms:** Add a required signature step to a custom form.
***
## Use Case Examples
### Example 1: Capturing a required signature
**Scenario:** Collect a customer authorization signature and store the resulting image when it changes.
```html
```
```js
// authorization.js
import { LightningElement } from 'lwc';
export default class Authorization extends LightningElement {
signature;
handleChange(event) {
this.signature = event.detail.dataURL; // Base64 PNG data URL
}
}
```
**Result:** A blue-ink signature pad on a white background; each stroke fires `change` with the current image as a Base64 PNG.
### Example 2: Signature with a custom Save action
**Scenario:** Add a Save button into the toolbar area and hide buttons you don't need.
```html
```
```js
// signOff.js
import { LightningElement } from 'lwc';
export default class SignOff extends LightningElement {
disabledButtons = ['background', 'paintbrush'];
signature;
handleChange(event) {
this.signature = event.detail.dataURL;
}
handleSave() {
// persist this.signature
}
}
```
**Result:** A signature pad with the background and paintbrush buttons removed and a brand "Save" button in the actions slot.
***
## Specifications
### Attributes
| Name | Description | Type | Default | Required |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ---------------------- | -------- |
| `background-button-alternative-text` | Alternative text for the background button. | String | `"'Background color'"` | |
| `background-color` | Defines the color of the background | String | `"#ffffff00"` | |
| `clear-button-alternative-text` | Alternative text for the clear button. | String | `"'Clear'"` | |
| `color` | Color of the pen. | String | `"#000"` | |
| `color-button-alternative-text` | Alternative text for the color button. | String | `"'Pen color'"` | |
| `disabled` | If present, the input field is disabled and users cannot interact with it. | Boolean | `false` | |
| `disabled-buttons` | Array of buttons to remove from the toolbar. Values include pen, paintbrush, eraser, ink, size, color, background, download, undo, redo, clear. | string\[] | — | |
| `download-button-alternative-text` | Alternative text for the download button. | String | `"'Download PNG'"` | |
| `draw-button-alternative-text` | Alternative text for the draw button. | String | `"'Draw'"` | |
| `erase-button-alternative-text` | Alternative text for the erase button. | String | `"'Erase'"` | |
| `field-level-help` | Help text detailing the purpose and function of the input. | String | — | |
| `hide-controls` | If present, hide the tool bar. | Boolean | `false` | |
| `ink-button-alternative-text` | Alternative text for the ink button. | String | `"'Ink'"` | |
| `label` | Text label for the input. | String | — | |
| `message-when-value-missing` | Error message to be displayed when the value is missing. | String | — | |
| `mode` | Current mode of input. Valid modes include draw, paint, ink and erase. | String | `"draw"` | |
| `paint-button-alternative-text` | Alternative text for the paint button. | String | `"'Paint'"` | |
| `read-only` | If present, the input field is read-only and cannot be edited by users. | Boolean | `false` | |
| `redo-button-alternative-text` | Alternative text for the redo button. | String | `"'Redo'"` | |
| `required` | If present, the input field must be filled out before the form is submitted. | Boolean | `false` | |
| `required-alternative-text` | The assistive text when the required attribute is set to true. | String | — | |
| `show-signature-pad` | If present, adds signature pad at the bottom of input. Also sets default drawing mode to ink. | Boolean | `false` | |
| `size` | Size of the pen. | String | `3` | |
| `size-button-alternative-text` | Alternative text for the size button. | String | `"'Size'"` | |
| `undo-button-alternative-text` | Alternative text for the undo button. | String | `"'Undo'"` | |
| `validity` | Represents the validity state of the input field, with respect to constraint validation. | String | — | |
| `value` | Input value encoded as Base64. Ex: 'data:image/png;base64, …' | String | — | |
| `variant` | The variant changes the appearance of the toolbar. Accepted variant is bottom-toolbar and top-toolbar which causes the toolbar to be displayed below the box. | String | `"bottom-toolbar"` | |
### Methods
| Name | Description | Argument Name | Argument Type | Argument Description |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ------------- | ----------------------------------------------------------------------------------------------- |
| `checkValidity` | Checks if the input is valid. | | | |
| `clear` | Clears the canvas. If clear is considered automated, it will not be saved as an undo-able action. | | | |
| `download` | Downloads the input field content as PNG. | | | |
| `focus` | Set the focus on the first focusable element. | | | |
| `redo` | Redo the last stroke that was undid. | | | |
| `reportValidity` | Displays the error messages. If the input is valid, `reportValidity()` clears displayed error messages. | | | |
| `setCustomValidity` | Sets a custom error message to be displayed when a form is submitted. | `message` | String | The string that describes the error. If message is an empty string, the error message is reset. |
| `setMode` | Set the drawing mode. Valid modes include draw, paint, ink and erase. | `modeName` | String | |
| `showHelpMessageIfInvalid` | Displays error messages on invalid fields. An invalid field fails at least one constraint validation and returns false when `checkValidity()` is called. | | | |
| `undo` | Undo the last stroke. | | | |
### Slots
| Slot | Description |
| --------- | ------------------------------- |
| `actions` | Placeholder for custom actions. |
### Custom Events
#### `blur`
The event fired when the focus is removed from the input.
The `blur` event doesn't return any parameters.
| Property | Value | Description |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles | false | This event does not bubble. |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed | false | This event does not propagate outside of the component in which it was dispatched. |
#### `change`
The event fired when the value changed.
The `change` event returns the following parameters.
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| `dataURL` | string | Base64 value of the input. |
The event properties are as follows.
| Property | Value | Description |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles | false | This event does not bubble. |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed | false | This event does not propagate outside of the component in which it was dispatched. |
#### `focus`
The event fired when the focus is set on the input.
The `focus` event doesn't return any parameters.
| Property | Value | Description |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles | false | This event does not bubble. |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed | false | This event does not propagate outside of the component in which it was dispatched. |
### Styling Hooks
| CSS Variable | Type | Default |
| --------------------------------------- | ----- | --------- |
| `--avonni-input-pen-body-sizing-height` | size | `350px` |
| `--avonni-input-pen-header-text-color` | color | `#3e3e3c` |
| `--avonni-input-pen-header-font-size` | font | `0.75rem` |
| `--avonni-input-pen-header-font-style` | font | `normal` |
| `--avonni-input-pen-header-font-weight` | font | `400` |
## Key Considerations
* **Output format:** The captured signature is a Base64 PNG data URL read from `event.detail.dataURL`.
* **Drawing modes:** `draw`, `paint`, `ink`, and `erase` change how strokes are rendered; `show-signature-pad` defaults the mode to `ink`.
* **Toolbar control:** Use `disabled-buttons` to remove buttons, or `hide-controls` to hide the toolbar entirely.
* **Validation:** Combine `required` with `message-when-value-missing` and `reportValidity()` to enforce a signature.
* **Touch support:** Works with mouse, stylus, and touch input.
* **Best Practice:** Set a contrasting `background-color` and `color`, and provide `message-when-value-missing` when the field is `required` so validation reads clearly.
***
## Troubleshooting Common Issues
* **Strokes not visible:** Ensure `color` contrasts with `background-color` and the pad is not `disabled` or `read-only`.
* **No value captured:** Read the signature from `event.detail.dataURL` in the `change` handler, not from the attribute directly.
* **Toolbar button missing:** Check it isn't listed in `disabled-buttons` and that `hide-controls` is not set.
* **If issues persist:** Contact our support team at for assistance.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.avonnicomponents.com/lwc-components/core-components/signature-pad.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.