Signature pad

ProReact Native · Expo

A signature field with real ink: the line thins as the pen speeds up and swells when it slows, touch points are smoothed into curves, and the finished signature can be undone stroke by stroke, replayed at the rhythm it was signed and exported as SVG.

View as Markdown

Installation

$ npx shadcn@latest add @goodui-native-pro/signature-pad

Then run npx expo install --fix so react-native-gesture-handler, react-native-reanimated, react-native-svg match your Expo SDK. Files land in components/goodui-native/signature-pad.

Pro components and screens install from the license-gated @goodui-native-pro registry. Setup: Pro access.

Usage

import { useRef, useState } from "react";
import { View } from "react-native";
import { Button } from "@/components/goodui-native/button/button";
import { SignaturePad, type SignaturePadHandle } from "@/components/goodui-native/signature-pad/signature-pad";

export function SignStep({ onSigned }: { onSigned: (svg: string) => void }) {
  const pad = useRef<SignaturePadHandle>(null);
  const [empty, setEmpty] = useState(true);

  return (
    <View style={{ gap: 12 }}>
      <SignaturePad ref={pad} accessibilityLabel="Signature" hint="Sign above the line" onChange={setEmpty} />
      <Button disabled={empty} onPress={() => onSigned(pad.current?.toSVG({ trim: true, color: "black" }) ?? "")}>
        Confirm signature
      </Button>
    </View>
  );
}

When to use

Use it for
  • Signing for something on the phone: a delivery, a lease, a waiver, a work order, a consent form.
  • Any flow that has to keep the signature: export it as SVG for the document, or store the pen data and show it again later.
  • Showing a stored signature read only (pass defaultValue and readOnly), with a replay of how it was signed.
Reach for something else
  • Free drawing or sketching with colors, an eraser and layers: this keeps one ink and whole strokes.
  • Typing a name as a signature: use text-field with a script font.
  • Confirming an action that needs no record of the hand: use swipe-to-confirm or hold-to-confirm.

Examples

Your own buttons through the ref

<SignaturePad ref={pad} accessibilityLabel="Tenant signature" controls={false} onChange={setEmpty} />
<Button variant="secondary" disabled={empty} onPress={() => pad.current?.undo()}>Undo</Button>
<Button variant="secondary" disabled={empty} onPress={() => pad.current?.clear()}>Clear</Button>

Store the pen data, show it again and replay it

// save: JSON.stringify(pad.current?.getData())
<SignaturePad ref={pad} accessibilityLabel="Signature on file" defaultValue={stored} readOnly />
<Button onPress={() => pad.current?.replay()}>Replay</Button>

Inside a ScrollView: stop the page from scrolling while the pen is down

<ScrollView scrollEnabled={!drawing}>
  <SignaturePad accessibilityLabel="Signature" onDrawingChange={setDrawing} />
</ScrollView>

Blue ink and a finer nib, no signing line

<SignaturePad accessibilityLabel="Card signature" color={colors.accent} minStrokeWidth={1} maxStrokeWidth={3.2} baseline={false} height={96} />

API reference

PropTypeDefault
accessibilityLabel*
Name of the field for screen readers, for example "Signature".
string—
ref
Imperative handle: `clear`, `undo`, `replay`, `isEmpty`, `toSVG`, `getData`.
Ref<SignaturePadHandle>—
onChange
Called when the pad becomes empty or stops being empty.
(empty: boolean) => void—
onDrawingChange
Called with `true` when a stroke starts and `false` when it ends, for example to lock a parent ScrollView.
(drawing: boolean) => void—
defaultValue
A signature to show at mount, from `getData()`. It is scaled to fit this pad.
SignatureData—
hint
Small text under the baseline, for example "Sign above the line".
string—
baseline
Draws the signing line with its cross. Default `true`.
booleantrue
controls
Shows the built-in replay, undo and clear buttons once there is ink. Default `true`.
booleantrue
height
Height of the pad in points. Default 200.
number200
color
Ink color. Defaults to the theme foreground.
string—
minStrokeWidth
Line width at full speed, in points. Default 1.3.
number1.3
maxStrokeWidth
Line width when the pen is slow, in points. Default 4.6.
number4.6
replaySpeed
Replay speed: 1 is the signed rhythm, 2 twice as fast. Default 1.
number1
haptic
`false` silences the undo and clear haptics. Default `true`.
booleantrue
readOnly
Shows the ink at full strength but takes no strokes and hides the controls: a signature on file. Replay through the ref still works.
booleanfalse
disabled
Takes no strokes and dims the pad.
booleanfalse
labels
Overrides for the built-in strings; a GooduiLocaleProvider pack sets them app-wide.
Partial<SignaturePadLabels>—
style
Style for the outer container.
StyleProp<ViewStyle>—
testID
Identifier for end-to-end tests.
string—

Motion and haptics

  • Ink: every touch point is joined to the last through a quadratic curve between their midpoints, sampled every 2.6 pt. The width eases toward a target set by pen speed, from maxStrokeWidth when slow to minStrokeWidth at 1.4 pt per ms.
  • Touch down inks a dot at once. Lifting tapers the line to half its width, and a fast release flicks up to 16 pt further in the direction of travel, thinning to a point.
  • Replay: the ink is redrawn stroke by stroke with the original timing; pauses between strokes are kept, capped at 420 ms. Touching the pad or calling undo or clear ends it.
  • Undo and clear fade the removed ink out in 200 ms. The controls spring in on snappy when the first stroke lands.
  • Reduced motion: drawing is unchanged (it is the input), replay does nothing, removed ink disappears at once and the controls appear without the spring.
  • Haptic: undo when a stroke is taken back
  • Haptic: delete when the pad is cleared
  • Haptic: none while drawing: the finger is already on the glass
  • Drawing runs on the UI thread: the pan gesture appends text to one animated SVG path, so a stroke never re-renders React. React renders once per finished stroke, to move it into a static path.
  • A stroke is appended to, never rebuilt, and a replay is a prefix of the same text, so cost per frame does not grow with the length of the signature.
  • The ink is filled geometry, about 100 characters per 2.6 pt of line: a full signature exports to roughly 40 to 120 KB of SVG.

Accessibility

  • The pad is a labelled region (accessibilityLabel is required) whose value reads 'Not signed' or 'Signed'.
  • Once there is ink the region carries two screen reader actions, 'Clear signature' and 'Undo last stroke'; clearing announces 'Not signed'.
  • The built-in replay, undo and clear controls are real buttons with names, 32 pt with a 6 pt hit slop.
  • On the web the pad takes keyboard focus: Delete or Backspace clears it and Ctrl or Cmd + Z takes back a stroke.
  • A signature cannot be drawn with a screen reader or a keyboard: offer another way to consent (a typed name, a checkbox) next to it.

Notes for AI

  • accessibilityLabel is required. Read emptiness from onChange (true means empty) or ref.isEmpty(); do not track strokes yourself.
  • Export with ref.toSVG(). It returns an empty string when nothing is signed. The default ink is currentColor, which renders black on its own; pass { color } to fix it, and { trim: true } to crop to the ink. Do not export the theme foreground of dark mode: it is nearly white.
  • To restore a signature pass getData() back as defaultValue (plain JSON). It is read once at mount and scaled to fit; remount with a new key to load another.
  • The pad fills its parent's width; set height (default 200). Strokes are kept in pad coordinates, so do not resize it while it holds ink.
  • Inside a ScrollView set scrollEnabled={!drawing} from onDrawingChange.
  • controls={false} hides the built-in buttons; wire your own to ref.undo(), ref.clear() and ref.replay().
  • readOnly shows a stored signature at full strength with no strokes and no controls; disabled also dims it. Use readOnly for a signature on file.
  • Requires GestureHandlerRootView at the app root (see the foundation setup). No Skia, no canvas: react-native-svg only.