# Signature Pad

> A React signature pad: draw with a finger, pen or mouse in ink that thins with speed, or type a name, then export it as PNG or SVG.

- Type: React component (Inputs)
- Access: Pro (the source needs a Wingo UI Pro plan, see https://wingo-ui.com/pricing)
- Version: 1.0.0
- Install: `npx wingo-ui@latest add signature-pad`
- Docs: https://wingo-ui.com/components/signature-pad

## Interaction

Draw on the dashed area with a finger, a stylus or the mouse: the ink follows the pointer at full frame rate, gets thinner when you move fast and thicker when you slow down, and a tap leaves a dot. The page still scrolls when you swipe outside the area. The placeholder fades away with the first stroke and a small frosted toolbar fades in at the top corner with Undo (removes the last stroke) and Clear (removes everything); on touch screens each is a 44px target and long press shows its name. Tab reaches the Draw / Type switch first (arrows move between the two), then the drawing area: there mod+z undoes the last stroke and Delete or Backspace clears it, and a screen reader hears Signature added and Signature cleared. Type switches to a name field: the name appears on the baseline in a handwriting font and shrinks to fit when it is long. The ink is the text color on screen (white in dark mode) and repaints when the theme changes; exports are always dark ink on a transparent background, cropped to the signature. Rotating a phone keeps the signature, scaled to fit the new size. Read-only shows the saved signature as an image without the toolbar.

## Installation

```bash
npx wingo-ui@latest add signature-pad
```

Pro item: run `npx wingo-ui@latest login` once with a Pro account. The CLI adds the files, their dependencies and a version record for updates.

With shadcn: `npx shadcn@latest add @wingo-ui/signature-pad` (needs the @wingo-ui registry with your API key in components.json)

Files:

- `components/ui/signature-pad.tsx`

npm dependencies: `npm i signature_pad motion lucide-react`

Wingo UI dependencies (installed automatically):

- [Field](https://wingo-ui.com/components/field) ([Markdown](https://wingo-ui.com/components/field.md))
- [Button](https://wingo-ui.com/components/button) ([Markdown](https://wingo-ui.com/components/button.md))
- [Segmented Control](https://wingo-ui.com/components/segmented-control) ([Markdown](https://wingo-ui.com/components/segmented-control.md))
- [Input](https://wingo-ui.com/components/input) ([Markdown](https://wingo-ui.com/components/input.md))
- [Tooltip](https://wingo-ui.com/components/tooltip) ([Markdown](https://wingo-ui.com/components/tooltip.md))
- [File export](https://wingo-ui.com/components/file-export) ([Markdown](https://wingo-ui.com/components/file-export.md))
- [useControllableState](https://wingo-ui.com/components/use-controllable-state) ([Markdown](https://wingo-ui.com/components/use-controllable-state.md))
- [Motion presets](https://wingo-ui.com/components/motion) ([Markdown](https://wingo-ui.com/components/motion.md))
- [UIProvider](https://wingo-ui.com/components/ui-config) ([Markdown](https://wingo-ui.com/components/ui-config.md))

## Usage

```tsx
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { SignaturePad, isSignatureEmpty, type SignatureData, type SignaturePadApi } from "@/components/ui/signature-pad"

export function ConfirmDelivery() {
  const [signature, setSignature] = useState<SignatureData | null>(null)
  const [api, setApi] = useState<SignaturePadApi | null>(null)

  const confirm = async () => {
    const png = await api?.toBlob()
    if (png) console.log("Signature", png.size, "bytes")
  }

  return (
    <div className="flex max-w-md flex-col gap-4">
      <SignaturePad
        label="Recipient signature"
        description="Sign with your finger or mouse"
        required
        value={signature}
        onValueChange={setSignature}
        setApi={setApi}
        placeholder="Sign here"
        fileName="Recipient signature"
      />
      <Button size="lg" disabled={isSignatureEmpty(signature)} onClick={confirm}>
        Confirm delivery
      </Button>
    </div>
  )
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value?` | `SignatureData \| null ({ kind: "drawn"; strokes: SignatureStroke[]; width: number; height: number } \| { kind: "typed"; text: string; font: string })` |  | The controlled signature; null when empty. Drawn strokes are in css px of a width x height box and are scaled by width when shown at another size, so a signature saved on a phone fits a desktop pad. |
| `defaultValue?` | `SignatureData \| null` | `"null"` | The uncontrolled start, for example a saved signature. A form reset puts it back. |
| `onValueChange?` | `(value: SignatureData \| null) => void` |  | Fires when a stroke ends (never per point), after undo and clear, when the mode switches and as you type. |
| `onEnd?` | `() => void` |  | A stroke finished. |
| `modes?` | `SignatureMode[] ("draw" \| "type")` | `"[\"draw\", \"type\"]"` | The ways to sign. With one entry the Draw / Type switch is hidden. Type is the keyboard and screen reader path, so keep it unless another one exists. |
| `mode?` | `"draw" \| "type"` |  | The controlled mode. A typed value from outside switches to type, a drawn one to draw. |
| `onModeChange?` | `(mode: SignatureMode) => void` |  | The person switched between Draw and Type. |
| `defaultMode?` | `"draw" \| "type"` | `"draw"` | The uncontrolled starting mode. Each mode keeps its own draft, so switching back restores the strokes or the name. |
| `label?` | `ReactNode` | `""` | The field label. It names the drawing area (aria-labelledby) and becomes the name field's label in type mode; a click on it focuses the pad. |
| `description?` | `ReactNode` | `""` | Helper text under the pad, linked with aria-describedby. The error takes its place while it shows. |
| `error?` | `ReactNode` | `""` | Replaces the description with the animated error, rings the surface red and sets aria-invalid. |
| `placeholder?` | `string` | `"Sign here"` | Centered in the empty surface above the baseline; fades out with the first stroke. Empty shows nothing. |
| `variant?` | `"soft" \| "outline"` | `"outline"` | outline is a dashed 2px zone (a signing area reads as a place to act), soft is the filled field look for forms full of soft inputs. |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | The label, the typed name field (32 / 40 / 48px) and the switch and toolbar buttons (lg gets 40px buttons). |
| `radius?` | `"none" \| "sm" \| "md" \| "lg" \| "full"` | `"md"` | The surface corners: none, 12px, 16px (md), 24px; full falls back to 24px. The name field takes the same radius. |
| `height?` | `number` | `200` | Surface height in px; the width is the container's. 200 fits a phone, 240 is roomy for couriers. |
| `penColor?` | `string` | `"currentColor"` | The ink on screen. currentColor reads the surface's text color (the foreground token, so white ink in dark mode) and repaints on theme changes; set classNames.surface to a text color class for a themed ink. Strokes drawn with a custom color keep it. |
| `exportColor?` | `string` | `"#111111"` | The ink in every export, whatever the theme: dark ink on a transparent background reads on any document. #1F3A93 is a classic blue pen. |
| `minWidth?` | `number` | `0.8` | The thinnest stroke in px, reached on fast movements (signature_pad). |
| `maxWidth?` | `number` | `2.8` | The thickest stroke in px, reached on slow movements and dots. |
| `velocityFilterWeight?` | `number` | `0.7` | How much the previous speed smooths the next width, 0 to 1 (signature_pad). Higher is calmer ink. |
| `guide?` | `boolean` | `true` | A dashed baseline at 72% of the height with a × at its start, where people expect to sign. |
| `typedFont?` | `string` | `"\"Segoe Script\", \"Snell Roundhand\", \"Brush Script MT\", \"Apple Chancery\", cursive"` | The typed signature's font stack. System fonts only, nothing downloads; exports use the same stack. Exported as DEFAULT_SIGNATURE_FONT for rendering a typed signature elsewhere (a PDF, an email). |
| `showToolbar?` | `boolean` | `true` | Undo and Clear at the top corner of the drawing area, shown once there is ink (type mode clears from the name field). Off when your own buttons do it through the api. |
| `trimExport?` | `boolean` | `true` | Exports crop to the signature's bounds plus 12px of padding. Off keeps the full pad box, the signature where it was drawn. |
| `fileName?` | `string` | `"signature"` | The base name for api.download(), with the local date and time appended ("Signature-2026-09-24-1640.png"). |
| `setApi?` | `(api: SignaturePadApi) => void` |  | Called after mount and whenever the export settings change. SignaturePadApi: clear(), undo(), isEmpty(), getValue(), toBlob({ type, quality, trim, padding = 12, scale = 2, background, color }), toSVG({ trim, padding, background, color }), toDataURL(type = "image/png" \| "image/svg+xml"), download({ format = "png" \| "svg", ...toBlob options }) resolving with the file name. |
| `required?` | `boolean` | `false` | The red mark after the label and aria-required. The check itself belongs to your form: isSignatureEmpty(value), exported by the file, is true for null, no strokes or a blank typed name. |
| `invalid?` | `boolean` | `false` | The invalid look (a red ring and a red dashed border) and aria-invalid without a message. |
| `disabled?` | `boolean` | `false` | Dims to 50%, the pen stops listening, no toolbar, the switch and the name field are disabled. |
| `readOnly?` | `boolean` | `false` | Shows the signature as an image (role="img", named by the label and, for a typed one, the name) without the switch, the name field or the toolbar. |
| `name?` | `string` | `""` | Form field name: a hidden input carries the signature as a PNG data url (export color, trimmed), updated after each stroke. A form reset puts defaultValue back. |
| `id?` | `string` |  | The drawing area's id (the name field's in type mode). Defaults to useId(); the label points at it. |
| `fieldProps?` | `Partial<FieldProps>` |  | Anything else for the Field wrapper: optional, labelAction, orientation, labelWidth, hideLabel. |
| `labels?` | `Partial<SignaturePadLabels>` |  | Every visible and announced string: draw, type, modes, typePlaceholder, undo, clear, canvas, canvasHint, signature, added, undone, cleared, empty, downloaded(fileName). English defaults in DEFAULT_SIGNATURE_PAD_LABELS. |
| `classNames?` | `Partial<Record<"root" \| "modes" \| "surface" \| "canvas" \| "typed" \| "input" \| "preview" \| "guide" \| "placeholder" \| "toolbar" \| "button" \| "field" \| "label" \| "description" \| "error" \| "counter", string>>` |  | Extra classes for the inner parts. A text color on surface is the on-screen ink when penColor is currentColor. |

## Parts

### isSignatureEmpty (function)

isSignatureEmpty(value): true for null, a drawn value with no strokes or a typed value with a blank name. Use it to gate a submit button or a required check.

### DEFAULT_SIGNATURE_PAD_LABELS (constant)

The English strings for the switch, toolbar, placeholders and screen reader announcements. Spread it and override a few keys through labels.

### DEFAULT_SIGNATURE_FONT (constant)

The system script font stack typed signatures use by default. Reuse it to render a typed signature in a PDF or an email.

### SignatureData (type)

The saved value: { kind: "drawn", strokes, width, height } or { kind: "typed", text, font }. Store it as JSON to show the signature again later.

### SignaturePadApi (type)

What setApi hands you: clear, undo, isEmpty, getValue, toBlob, toSVG, toDataURL and download.

### SignaturePadProps (type)

The props of SignaturePad, for wrappers that pass them through.

## Examples

- **Typed signature**: Type mode with a script font, exported as a PNG.
- **Courier delivery**: A phone-sized screen: a taller pad and a confirm button that waits for ink.
- **Blue ink**: exportColor #1F3A93 with a wider pen; on screen the ink follows a themed text color.
- **Read-only**: A saved signature with the signing date, shown as an image.
- **Validation**: Required: sending without a signature shows the error.
- **Soft, in a form**: variant soft next to soft inputs.

## See also

- [File export](https://wingo-ui.com/components/file-export) ([Markdown](https://wingo-ui.com/components/file-export.md))
- [File Upload](https://wingo-ui.com/components/file-upload) ([Markdown](https://wingo-ui.com/components/file-upload.md))
- [Image Cropper](https://wingo-ui.com/components/image-cropper) ([Markdown](https://wingo-ui.com/components/image-cropper.md))
- [QR Code](https://wingo-ui.com/components/qr-code) ([Markdown](https://wingo-ui.com/components/qr-code.md))
- [Form Wizard](https://wingo-ui.com/components/form-wizard) ([Markdown](https://wingo-ui.com/components/form-wizard.md))

---

Canonical: https://wingo-ui.com/components/signature-pad
More components: https://wingo-ui.com/components · Index for agents: https://wingo-ui.com/llms.txt