# Signature pad

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

- Type: Component (inputs)
- Access: Pro
- Page: https://goodui.dev/native/components/signature-pad
- Markdown: https://goodui.dev/native/components/signature-pad.md
- Registry item: https://goodui.dev/native/r/signature-pad.json
- Dependencies: react-native-gesture-handler, react-native-reanimated, react-native-svg
- Keywords: react native signature pad, signature capture expo, sign on screen, e-signature field, signature to svg, draw signature react native svg, handwriting ink pressure, signature replay

## When to use

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

## When not to use

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

## Installation

With the shadcn CLI (needs a components.json in the Expo app), then `npx expo install --fix` so native dependencies match your Expo SDK. The foundation comes along the first time.

```bash
npx shadcn@latest add @goodui-native-pro/signature-pad
npx expo install --fix
```

Pro: add `"@goodui-native-pro": { "url": "https://goodui.dev/native/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${GOODUI_LICENSE_KEY}" } }` to the `registries` of components.json and put your license key in .env.local.

The component lands in `components/goodui-native/signature-pad/` and imports the foundation from `components/goodui-native/foundation/` with relative paths; it also installs locale.

Built-in strings follow `<GooduiLocaleProvider>` (one [language pack](https://goodui.dev/native/r/locale-tr.json) translates the whole kit); the `labels` prop overrides them for one instance.

## Usage

```tsx
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>
  );
}
```

## Examples

### Your own buttons through the ref

```tsx
<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

```tsx
// 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

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

### Blue ink and a finer nib, no signing line

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

## API reference

### SignaturePad

`import { SignaturePad } from "@/components/goodui-native/signature-pad/signature-pad";`

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

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

## Motion

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

## Haptics

- undo when a stroke is taken back
- delete when the pad is cleared
- none while drawing: the finger is already on the glass

## Performance

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

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

## Related

- [Text field](https://goodui.dev/native/components/text-field.md): A text field whose label glides up as you focus it, with helper and error text that slide in, a shake and haptic on error, clear and reveal buttons, a character counter and a multiline mode that grows with its text.
- [Swipe to confirm](https://goodui.dev/native/components/swipe-to-confirm.md): Slide to confirm: the thumb follows the finger 1:1, the track fills behind it and the label fades, a tick marks the point of no return, and at the end the track gathers into a spinner and opens into the result.
- [Hold to confirm](https://goodui.dev/native/components/hold-to-confirm.md): Confirms an irreversible action by holding: ink fills from the leading edge, the label inverts where the ink passes, and haptics tick at every quarter.
- [Checkbox and radio](https://goodui.dev/native/components/checkbox.md): Checkboxes whose check draws itself in (an indeterminate dash retracts into it) and radios whose dot pops into the center, inline or as list rows, with CheckboxGroup and RadioGroup helpers.

## Guidance for AI tools

Signature pad: 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. Use only the documented props. Keep accessibility, reduced motion and both color schemes intact when adapting it.

Full library index: https://goodui.dev/native/llms.txt
