webflow-clipboard

Copy to Webflow / Paste from Webflow as a reusable npm library. Put Xscp JSON on the clipboard in the format Webflow Designer expects (so users can Cmd+V in Designer), or extract Xscp from a paste event.

Use the core API in any JS/TS app, or the React components for a ready "Copy to Webflow" button.

Repository

• Source code: https://github.com/bejamas/webflow-clipboard
• Issues: https://github.com/bejamas/webflow-clipboard/issues

Two use cases (Jobs To Be Done)

1) Copy to Webflow (write Xscp to clipboard)

Job statement When I have component data outside Webflow (CMS, app UI, Git, DB), I want to copy it in Webflow-compatible clipboard format, so I can paste it into Webflow Designer in one step.

What this package helps achieve

• Build a reliable "Copy to Webflow" button that works with Cmd/Ctrl+V in Designer.
• Remove brittle clipboard hacks and reduce "clipboard is empty" failures.
• Speed up migration and content operations from external tools into Webflow.

2) Copy from Webflow (parse paste event to JSON)

Job statement When I copy an element in Webflow Designer, I want to parse its Xscp payload into valid JSON in my app, so I can store, version, transform, validate, or reuse that structure outside Webflow.

What this package helps achieve

• Capture Webflow payloads through getXscpFromPasteEvent / usePasteFromWebflow.
• Create internal tooling for backup, audit, and reusable component workflows.
• Turn visual edits into structured JSON that can be processed in pipelines.

Install

npm install webflow-clipboard
# or
bun add webflow-clipboard
# or
pnpm add webflow-clipboard

Quick start — React "Copy to Webflow" button

import { CopyToWebflowButton } from "webflow-clipboard/react";

// Your Xscp JSON (e.g. from your CMS, Git, or "Paste from Webflow")
const xscpJson = '{"type":"@webflow/XscpData","payload":{...}}';

export function MyComponent() {
  return (
    <CopyToWebflowButton
      xscpJson={xscpJson}
      className="rounded-full bg-black text-white px-4 py-2"
      showMessage
    />
  );
}

On click, the button copies the JSON to the clipboard so the user can open Webflow Designer and press Cmd+V (Mac) or Ctrl+V (Windows).

Core API (no React)

Use in any environment (Node scripts, vanilla JS, other frameworks):

import {
  writeClipboardXscp,
  normalizeXscp,
  validateCopyPayload,
  getXscpFromPasteEvent,
} from "webflow-clipboard";

// Copy Xscp to clipboard (must run in a user gesture / browser context)
writeClipboardXscp(xscpJsonString);

// Normalize / validate before copy
const result = validateCopyPayload(rawString);
if (result.valid) {
  writeClipboardXscp(rawString);
}

// In a paste handler (e.g. onPaste on a contenteditable or textarea)
element.addEventListener("paste", (e) => {
  const json = getXscpFromPasteEvent(e);
  if (json) {
    e.preventDefault();
    console.log("Pasted Webflow JSON", json);
  }
});

React hooks

useCopyToWebflow

Build your own button or trigger copy from code:

import { useCopyToWebflow } from "webflow-clipboard/react";

function MyButton() {
  const { copyToWebflow, status, error, successMessage } = useCopyToWebflow({
    successMessage: "Copied! Paste in Webflow Designer with Cmd+V.",
  });

  return (
    <div>
      <button onClick={() => copyToWebflow(xscpJson)}>Copy to Webflow</button>
      {error && <p role="alert">{error}</p>}
      {successMessage && <p>{successMessage}</p>}
    </div>
  );
}

usePasteFromWebflow

Implement a "Paste from Webflow" area (user copies in Designer, pastes in your app):

import { usePasteFromWebflow } from "webflow-clipboard/react";

function PasteArea() {
  const { json, onPaste, error, copyJson, copied } = usePasteFromWebflow();

  return (
    <div>
      <textarea
        onPaste={onPaste}
        value={json}
        placeholder="Click here, then Cmd+V (after copying in Webflow Designer)"
        readOnly
      />
      {error && <p role="alert">{error}</p>}
      {json && (
        <button onClick={copyJson}>{copied ? "Copied" : "Copy JSON"}</button>
      )}
    </div>
  );
}

API reference

Core (webflow-clipboard)

| Export | Description | |--------|-------------| | writeClipboardXscp(xscp) | Copies normalized Xscp to clipboard (both application/json and text/plain) so Webflow Designer accepts Cmd+V. | | normalizeXscp(raw) | Normalizes raw Xscp string; throws if invalid. | | normalizeCopyPayload(payload) | Extracts first JSON object from a string (for payloads with junk). | | validateCopyPayload(payload) | Returns { valid, length } or { valid: false, error, length, tailPreview? }. | | isXscpPayload(payload) | Returns true if payload looks like Webflow Xscp. | | getXscpFromPasteEvent(e) | From a ClipboardEvent, returns Xscp string or null. |

React (webflow-clipboard/react)

| Export | Description | |--------|-------------| | CopyToWebflowButton | Button that takes xscpJson and copies on click. | | useCopyToWebflow(options?) | Hook: copyToWebflow(xscp), status, error, successMessage, reset. | | usePasteFromWebflow() | Hook: json, onPaste, error, copyJson, copied, reset. |

Why this exists

Webflow Designer only accepts paste when the clipboard has application/json. Browsers don’t allow setting that via navigator.clipboard.write(); this library uses a programmatic copy event to set both application/json and text/plain, so Designer accepts Cmd+V.

For paste from Webflow, Xscp is only exposed on the paste event (not on normal clipboard read), so you need a paste handler; getXscpFromPasteEvent / usePasteFromWebflow do that.

License

MIT