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.

<!-- authorization.html -->
<template>
    <avonni-signature-pad
        label="Customer authorization"
        field-level-help="Sign inside the box using your mouse, stylus or finger."
        color="#1b96ff"
        background-color="#ffffff"
        size="3"
        mode="ink"
        show-signature-pad
        required
        message-when-value-missing="A signature is required to continue."
        onchange={handleChange}
    ></avonni-signature-pad>
</template>

// 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.

<!-- signOff.html -->
<template>
    <avonni-signature-pad
        label="Delivery sign-off"
        variant="bottom-toolbar"
        disabled-buttons={disabledButtons}
        onchange={handleChange}
    >
        <lightning-button
            slot="actions"
            label="Save"
            variant="brand"
            icon-name="utility:save"
            onclick={handleSave}
        ></lightning-button>
    </avonni-signature-pad>
</template>

// 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.

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 [email protected] for assistance.