vite-plugin-iframe-picker

A Vite plugin and SDK toolset for picking DOM elements inside a cross-origin iframe. Useful for building low-code editors, devtools, or visual inspectors.

Features

• 🚀 Vite Plugin: Automatically injects the picker client script into the iframe site.
• 🔌 Universal SDK: Pure JS class for controlling the picker from the parent site (React/Vanilla friendly).
• 💚 Vue Composition API: Dedicated useElementPicker hook for Vue 3 users.
• 🛡️ Cross-Origin Ready: Uses postMessage for secure communication.

Installation

npm install vite-plugin-iframe-picker

Setup

1. Configure the Iframe Site (Child)

Add the plugin to your vite.config.js in the project that will be loaded inside the iframe.

import { defineConfig } from 'vite'
import iframePicker from 'vite-plugin-iframe-picker'

export default defineConfig({
  plugins: [
    iframePicker() 
  ]
})

This will automatically inject the necessary client script during development and build.

2. Configure the Parent Site (Host)

Use the SDK to control the picking process.

Usage with Vue 3

<script setup>
import { ref } from 'vue'
import { useElementPicker } from 'vite-plugin-iframe-picker/vue'

const iframeRef = ref(null)
const { isPicking, start, stop } = useElementPicker({
  onPick: (data) => {
    console.log('Selected Element:', data)
  },
  onCancel: () => {
    console.log('Picking canceled')
  }
})

const startPicking = () => {
  if (iframeRef.value) {
    start({ iframeElement: iframeRef.value })
  }
}
</script>

<template>
  <button @click="startPicking" :disabled="isPicking">Pick Element</button>
  <button @click="stop" :disabled="!isPicking">Stop</button>
  
  <iframe ref="iframeRef" src="http://your-iframe-site.com"></iframe>
</template>

Usage with React / Vanilla JS

import { IframePickerClient } from 'vite-plugin-iframe-picker/parent'

const client = new IframePickerClient({
  onPick: (data) => console.log(data),
  onCancel: () => console.log('Canceled')
})

// Start listening for messages
client.listen()

// Start picking
function start() {
  const iframe = document.querySelector('iframe')
  client.start(iframe)
}

// Stop picking
function stop() {
  client.stop()
}

// Cleanup when component unmounts
// client.unlisten()

API Reference

PickerResult Object

{
  tagName: string;
  id: string;
  className: string;
  innerText: string;
  rect: { x, y, width, height }; // Bounding client rect
  selector: string; // CSS selector path
}

Ignoring Elements

To prevent an element inside the iframe from being pickable (e.g., your own overlays), add the data-picker-ignore attribute:

<div data-picker-ignore>
  This element cannot be picked.
</div>

License

MIT