{"slug":"signature-pad","title":"Signature Pad","description":"Using the signature pad component in your application","contentType":"component","framework":"vue","content":"A signature pad lets users draw handwritten signatures with pointer or touch\ninput.\n\n## Resources\n\n\n[Latest version: v1.39.1](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 input\n- Export signatures as data URLs\n- Clear signatures programmatically\n\n## Installation\n\nInstall the signature pad package:\n\n```bash\nnpm install @zag-js/signature-pad @zag-js/vue\n# or\nyarn add @zag-js/signature-pad @zag-js/vue\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\nImport the signature pad package:\n\n```tsx\nimport * as signaturePad from \"@zag-js/signature-pad\"\n```\n\nThe signature pad package exports two key functions:\n\n- `machine` - State machine logic.\n- `connect` - Maps machine state to JSX props and event handlers.\n\nThen use the framework integration helpers:\n\n```html\n<script setup>\n  import * as signaturePad from \"@zag-js/signature-pad\"\n  import { normalizeProps, useMachine } from \"@zag-js/vue\"\n  import { computed } from \"vue\"\n\n  const service = useMachine(signaturePad.machine, { id: \"1\" })\n\n  const api = computed(() => signaturePad.connect(service, normalizeProps))\n</script>\n\n<template>\n  <div v-bind=\"api.getRootProps()\">\n    <label v-bind=\"api.getLabelProps()\">Signature Pad</label>\n\n    <div v-bind=\"api.getControlProps()\">\n      <svg v-bind=\"api.getSegmentProps()\">\n        <path\n          v-for=\"(path, i) of api.paths\"\n          :key=\"i\"\n          v-bind=\"api.getSegmentPathProps({ path })\"\n        />\n        <path\n          v-if=\"api.currentPath\"\n          v-bind=\"api.getSegmentPathProps({ path: api.currentPath })\"\n        />\n      </svg>\n\n      <button v-bind=\"api.getClearTriggerProps()\">X</button>\n\n      <div v-bind=\"api.getGuideProps()\" />\n    </div>\n  </div>\n</template>\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```tsx\nconst service = useMachine(signaturePad.machine, {\n  onDraw(details) {\n    // details => { paths: string[] }\n    console.log(\"Drawing signature\", details)\n  },\n  onDrawEnd(details) {\n    // details => { paths: string[], getDataUrl: (type, quality?) => Promise<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```tsx\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```tsx\nconst service = useMachine(signaturePad.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```tsx\n<img src={imageURL} alt=\"Signature\" />\n```\n\n### Controlled signature paths\n\nUse `paths` and `onDraw` for controlled usage.\n\n```tsx\nconst service = useMachine(signaturePad.machine, {\n  paths,\n  onDraw(details) {\n    setPaths(details.paths)\n  },\n})\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```tsx\nconst service = useMachine(signaturePad.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```tsx\nconst service = useMachine(signaturePad.machine, {\n  drawing: {\n    size: 5,\n  },\n})\n```\n\n### Controlling pressure simulation\n\nPressure simulation is enabled by default. Set `drawing.simulatePressure` to\n`false` to use raw pointer pressure values.\n\n```tsx\nconst service = useMachine(signaturePad.machine, {\n  drawing: {\n    simulatePressure: false,\n  },\n})\n```\n\n### Usage in forms\n\nTo use the signature pad in a form, set the `name` context property.\n\n```tsx\nconst service = useMachine(signaturePad.machine, {\n  name: \"signature\",\n})\n```\n\nThen, render the hidden input element using `api.getHiddenInputProps()`.\n\n```tsx\n<input {...api.getHiddenInputProps({ value: imageURL })} />\n```\n\n### Customizing screen reader text\n\nUse `translations` to customize accessible text for the drawing control and\nclear trigger.\n\n```tsx\nconst service = useMachine(signaturePad.machine, {\n  translations: {\n    control: \"Signature drawing area\",\n    clearTrigger: \"Clear signature\",\n  },\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"}