<!-- Markdown twin of https://pixelvault.dev/docs/paste/ -->

# Paste & host (browser widget)

Let your own users paste, drop, or select an image in a textarea and get a hosted CDN URL inserted automatically — the same flow as GitHub's markdown editor, on your site. It runs entirely in the browser with a **publishable key**, so there's no server code to write.

## 1\. Create a publishable key

In your [dashboard](/dashboard/), open a project's **Publishable keys** section and add one with an allowlist of the origins it may be used from (for example `https://app.example.com`). Publishable keys (`pv_pub_…`) are safe to ship in browser code: they are **upload-only** and rejected from any origin that isn't on the allowlist. See [Authentication](/docs/authentication/#publishable-keys).

A publishable key can only upload. It can't list, read, or delete images, and it only works from the origins you allow — so putting it in your page source is fine.

## 2a. Drop-in script tag

Zero build step. Add one tag; every field matching `data-pv-target` becomes paste-and-host:

```
<textarea data-pixelvault></textarea>
<button data-pv-pick="[data-pixelvault]">Upload image</button>
<script src="https://pixelvault.dev/paste.js"
        data-pv-key="pv_pub_xxxxxxxx"
        data-pv-target="[data-pixelvault]"></script>
```

Attributes on the tag: `data-pv-key` (required), `data-pv-target` (CSS selector; defaults to `[data-pixelvault]`), and optional `data-pv-endpoint` / `data-pv-folder`. Add a `data-pv-pick` attribute to any button (its value is the target field's selector) to open the file picker on click. The script also exposes a global `window.PixelVaultPaste` with `attach`, `openFilePicker`, and `init` for wiring elements added later.

## 2b. npm package

For bundled apps, install the framework-agnostic core:

```
npm install @pixelvault-dev/paste
```

```
import { attachPaste, openFilePicker } from "@pixelvault-dev/paste";

const field = document.querySelector("textarea");
const options = { publishableKey: "pv_pub_xxxxxxxx" };

attachPaste(field, options);                       // paste + drop
uploadButton.addEventListener("click", () => openFilePicker(field, options));
```

Or a framework binding:

```
// npm install @pixelvault-dev/paste-react
import { useRef } from "react";
import { usePaste } from "@pixelvault-dev/paste-react";

function Editor() {
  const ref = useRef(null);
  const { openFilePicker } = usePaste(ref, { publishableKey: "pv_pub_xxxxxxxx" });
  return (
    <>
      <textarea ref={ref} />
      <button onClick={openFilePicker}>Upload image</button>
    </>
  );
}
```

```
<!-- npm install @pixelvault-dev/paste-vue -->
<script setup>
  import { ref } from "vue";
  import { usePaste } from "@pixelvault-dev/paste-vue";

  const field = ref(null);
  const { openFilePicker } = usePaste(field, { publishableKey: "pv_pub_xxxxxxxx" });
</script>

<template>
  <textarea ref="field" />
  <button @click="openFilePicker">Upload image</button>
</template>
```

Using a rich-text editor instead of a textarea? Use the lower-level `uploadImage()` helper with the editor's native insertion API. See the complete [Lexical image upload plugin](/prompts/lexical-image-paste/) and [Quill paste and drop handler](/prompts/quill-image-paste/).

## 3\. What the user sees

Pasting, dropping, or picking an image inserts an `![Uploading…]()` placeholder at the caret, uploads the file, then swaps in `![name](https://img.pixelvault.dev/…)`. Override the inserted text (HTML, BBCode, a bare URL) with the `render` option, and hook `onUploadStart`, `onUploadComplete`, and `onError` for progress and error handling.

## Next steps

-   [POST /v1/images](/docs/api/images/#upload_image): the endpoint the widget calls.
-   [Image transforms](/docs/transforms/) to resize pasted images on display.
-   [Prompts](/prompts/) that wire paste-and-host into React, Next.js, Tiptap and more.
