CynosureComponents / Controls
SignaturePad
A pad to draw a signature with a mouse, finger or pen.
When to useLink to "When to use"
- Collecting a handwritten signature for a document or a form.
Always offer another way. Drawing needs a pointer and steady hands; it cannot be done from a keyboard or with most assistive technology. Put the pad beside a typed-name option and an upload option (for example as Tabs in a Dialog), and point to them with aria-describedby.
UsageLink to "Usage"
import { SignaturePad } from "@arshad-shah/cynosure";
const [strokes, setStrokes] = useState<InkStroke[]>([]);
<SignaturePad label="Draw your signature" value={strokes} onChange={setStrokes} />onChange is called once per finished stroke with the whole list. Undo and clear are yours: drop the last stroke, or empty the list.
Pens, fingers and palmsLink to "Pens, fingers and palms"
- Pens: pressure (through a curve that lifts light writing) and tilt shape the line.
- Mouse and touch: a steady line, like a ballpoint (speed-based pressure makes lines wobble).
- One stroke at a time: a second finger, a right-click or a pen's barrel button never starts or replaces a stroke.
- Palm rejection: touches are ignored for three seconds after a pen was last seen.
Keeping its shapeLink to "Keeping its shape"
Pass space to record strokes in a fixed coordinate space. The signature then keeps its shape and weight whatever size the pad is shown at (a phone, a large screen, a resize while drawing).
SavingLink to "Saving"
inkToSvg(strokes, { width, height, ink, weight }) returns a standalone SVG for saving or placing in a PDF. inkPath(stroke, weight) gives one stroke's path data using only M, C and Z, which canvases and PDF writers read alike.
PropsLink to "Props"
| Prop | What it does | Type | Default |
|---|---|---|---|
labelRequired | Accessible name, e.g. "Draw your signature". | string | |
valueRequired | The strokes so far, in the pad's coordinate space. | InkStroke[] | |
onChangeRequired | Called once per finished stroke with the new list. Undo and clear are yours (slice or empty the list). | (strokes: InkStroke[]) => void | |
ink | Ink colour (any CSS colour). Default: the ink token, so it follows dark mode on screen. | string | the ink token |
weight | Nib size. Default medium. | InkWeight | `medium` |
space | The coordinate space strokes are recorded in. Without it strokes are in shown CSS pixels; with it a signature keeps its shape and weight however big the pad is shown (phone width, text size, a resize while drawing). | { width: number; height: number; } | |
width | Fixed size in CSS pixels. Default: the full width, and the height token. | number | the full width |
height | Fixed height in CSS pixels. Default: the height token. | number | the height token |
disabled | Stops drawing; the strokes so far stay shown. | boolean | |
aria-describedby | Ids of text that explains the pad (e.g. "Or type your name instead"). | string | |
className | Added to the root element, for layout. | string | |
style | Layout only. Restyle through --cy-signature-pad-* tokens. | CSSProperties |
Generated from the type definitions in @arshad-shah/cynosure 0.5.0.
Behaviour and accessibilityLink to "Behaviour and accessibility"
- Role: the canvas is an image named by
label; describe the other ways to sign witharia-describedby. - Touch: gestures on the pad draw instead of scrolling the page, and long-press menus are suppressed while drawing.
- Colour: without
ink, the ink token is used, so the line is dark on light and light on dark. In forced colours it uses the system text colour. - Disabled:
aria-disabled, nothing draws.
ThemingLink to "Theming"
Tokens: --cy-signature-pad-ink, --cy-signature-pad-background, --cy-signature-pad-height and --cy-signature-pad-guide.
RelatedLink to "Related"
These examples run Cynosure 0.5.0 (commit 50ce30b), the version on npm.