{"slug":"signature-pad","title":"Signature Pad","description":"Using the signature pad component in your application","contentType":"component","framework":"react","content":"The signature pad component allows users to draw handwritten signatures using\ntouch or pointer devices. The signature can be saved as an image or cleared.\n\n## Resources\n\n\n[Latest version: v1.31.0](https://www.npmjs.com/package/@zag-js/signature-pad)\n[Logic Visualizer](https://zag-visualizer.vercel.app/signature-pad)\n[Source Code](https://github.com/chakra-ui/zag/tree/main/packages/machines/signature-pad)\n\n\n\n**Features**\n\n- Draw signatures using touch or pointer devices\n- Save the signature as an image\n- Clear the signature\n\n## Installation\n\nTo use the signature pad machine in your project, run the following command in\nyour command line:\n\n```bash\nnpm install @zag-js/signature-pad @zag-js/react\n# or\nyarn add @zag-js/signature-pad @zag-js/react\n```\n\n## Anatomy\n\nTo set up the signature pad correctly, you'll need to understand its anatomy and\nhow we name its parts.\n\n> Each part includes a `data-part` attribute to help identify them in the DOM.\n\n\n\n## Usage\n\nFirst, import the signature pad package into your project\n\n```jsx\nimport * as signaturePad from \"@zag-js/signature-pad\"\n```\n\nThe signature pad package exports two key functions:\n\n- `machine` — The state machine logic for the signature pad widget.\n- `connect` — The function that translates the machine's state to JSX attributes\n  and event handlers.\n\nNext, import the required hooks and functions for your framework and use the\nsignature pad machine in your project 🔥\n\n```jsx\nimport { normalizeProps, useMachine } from \"@zag-js/react\"\nimport * as signaturePad from \"@zag-js/signature-pad\"\nimport { useId, useState } from \"react\"\n\nexport function SignaturePad() {\n  const service = useMachine(signaturePad.machine, {\n    id: useId(),\n  })\n\n  const api = signaturePad.connect(service, normalizeProps)\n\n  return (\n    <div {...api.getRootProps()}>\n      <label {...api.getLabelProps()}>Signature Pad</label>\n\n      <div {...api.getControlProps()}>\n        <svg {...api.getSegmentProps()}>\n          {api.paths.map((path, i) => (\n            <path key={i} {...api.getSegmentPathProps({ path })} />\n          ))}\n          {api.currentPath && (\n            <path {...api.getSegmentPathProps({ path: api.currentPath })} />\n          )}\n        </svg>\n\n        <button {...api.getClearTriggerProps()}>X</button>\n\n        <div {...api.getGuideProps()} />\n      </div>\n    </div>\n  )\n}\n```\n\n### Listening to drawing events\n\nThe signature pad component emits the following events:\n\n- `onDraw`: Emitted when the user is drawing the signature.\n- `onDrawEnd`: Emitted when the user stops drawing the signature.\n\n```jsx\nconst service = useMachine(signature.machine, {\n  onDraw(details) {\n    // details => { path: string[] }\n    console.log(\"Drawing signature\", details)\n  },\n  onDrawEnd(details) {\n    // details => { path: string[], toDataURL: () => string }\n    console.log(\"Signature drawn\", details)\n  },\n})\n```\n\n### Clearing the signature\n\nTo clear the signature, use the `api.clear()`, or render the clear trigger\nbutton.\n\n```jsx\n<button onClick={() => api.clear()}>Clear</button>\n```\n\n### Rendering an image preview\n\nUse the `api.getDataUrl()` method to get the signature as a data URL and render\nit as an image.\n\n> You can also leverage the `onDrawEnd` event to get the signature data URL.\n\n```jsx\nconst service = useMachine(signature.machine, {\n  onDrawEnd(details) {\n    details.getDataUrl(\"image/png\").then((url) => {\n      // set the image URL in local state\n      setImageURL(url)\n    })\n  },\n})\n```\n\nNext, render the image preview using the URL.\n\n```jsx\n<img src={imageURL} alt=\"Signature\" />\n```\n\n### Changing the stroke color\n\nTo change the stroke color, set the `drawing.fill` option to a valid CSS color.\n\n> Note: You can't use a css variable as the stroke color.\n\n```jsx\nconst service = useMachine(signature.machine, {\n  drawing: {\n    fill: \"red\",\n  },\n})\n```\n\n### Changing the stroke width\n\nTo change the stroke width, set the `drawing.size` option to a number.\n\n```jsx\nconst service = useMachine(signature.machine, {\n  drawing: {\n    size: 5,\n  },\n})\n```\n\n### Simulating pressure sensitivity\n\nPressure sensitivity is disabled by default. To enable it, set the\n`drawing.simulatePressure` option to `true`.\n\n```jsx\nconst service = useMachine(signature.machine, {\n  drawing: {\n    simulatePressure: true,\n  },\n})\n```\n\n### Usage in forms\n\nTo use the signature pad in a form, set the `name` context property.\n\n```jsx\nconst service = useMachine(signature.machine, {\n  name: \"signature\",\n})\n```\n\nThen, render the hidden input element using `api.getHiddenInputProps()`.\n\n```jsx\n<input {...api.getHiddenInputProps({ value: imageURL })} />\n```\n\n### Disabling the signature pad\n\nSet the `disabled` context property to `true` to disable the signature pad.\n\n```jsx\nconst service = useMachine(signature.machine, {\n  disabled: true,\n})\n```\n\n### Making the signature pad read-only\n\nSet the `readOnly` context property to `true` to make the signature pad\nread-only.\n\n```jsx\nconst service = useMachine(signature.machine, {\n  readOnly: true,\n})\n```\n\n## Methods and Properties\n\nThe signature pad `api` exposes the following methods and properties:\n\n### Machine Context\n\nThe signature pad machine exposes the following context properties:\n\n**`ids`**\nType: `Partial<{ root: string; control: string; hiddenInput: string; label: string; }>`\nDescription: The ids of the signature pad elements. Useful for composition.\n\n**`translations`**\nType: `IntlTranslations`\nDescription: The translations of the signature pad. Useful for internationalization.\n\n**`onDraw`**\nType: `(details: DrawDetails) => void`\nDescription: Callback when the signature pad is drawing.\n\n**`onDrawEnd`**\nType: `(details: DrawEndDetails) => void`\nDescription: Callback when the signature pad is done drawing.\n\n**`drawing`**\nType: `DrawingOptions`\nDescription: The drawing options.\n\n**`disabled`**\nType: `boolean`\nDescription: Whether the signature pad is disabled.\n\n**`required`**\nType: `boolean`\nDescription: Whether the signature pad is required.\n\n**`readOnly`**\nType: `boolean`\nDescription: Whether the signature pad is read-only.\n\n**`name`**\nType: `string`\nDescription: The name of the signature pad. Useful for form submission.\n\n**`defaultPaths`**\nType: `string[]`\nDescription: The default paths of the signature pad.\nUse when you don't need to control the paths of the signature pad.\n\n**`paths`**\nType: `string[]`\nDescription: The controlled paths of the signature pad.\n\n**`dir`**\nType: `\"ltr\" | \"rtl\"`\nDescription: The document's text/writing direction.\n\n**`id`**\nType: `string`\nDescription: The unique identifier of the machine.\n\n**`getRootNode`**\nType: `() => ShadowRoot | Node | Document`\nDescription: A root node to correctly resolve document in custom environments. E.x.: Iframes, Electron.\n\n### Machine API\n\nThe signature pad `api` exposes the following methods:\n\n**`empty`**\nType: `boolean`\nDescription: Whether the signature pad is empty.\n\n**`drawing`**\nType: `boolean`\nDescription: Whether the user is currently drawing.\n\n**`currentPath`**\nType: `string`\nDescription: The current path being drawn.\n\n**`paths`**\nType: `string[]`\nDescription: The paths of the signature pad.\n\n**`getDataUrl`**\nType: `(type: DataUrlType, quality?: number) => Promise<string>`\nDescription: Returns the data URL of the signature pad.\n\n**`clear`**\nType: `VoidFunction`\nDescription: Clears the signature pad.\n\n### Data Attributes\n\n**`Label`**\n\n**`data-scope`**: signature-pad\n**`data-part`**: label\n**`data-disabled`**: Present when disabled\n**`data-required`**: Present when required\n\n**`Root`**\n\n**`data-scope`**: signature-pad\n**`data-part`**: root\n**`data-disabled`**: Present when disabled\n\n**`Control`**\n\n**`data-scope`**: signature-pad\n**`data-part`**: control\n**`data-disabled`**: Present when disabled\n\n**`Guide`**\n\n**`data-scope`**: signature-pad\n**`data-part`**: guide\n**`data-disabled`**: Present when disabled","package":"@zag-js/signature-pad","editUrl":"https://github.com/chakra-ui/zag/edit/main/website/data/components/signature-pad.mdx"}