founder-grab
v1.0.3
Published
Element selection SDK for embedded applications - capture user feedback on web pages
Maintainers
santiagoimsReadme
founder-grab
Element selection SDK for embedded applications. Allows users to visually select page elements and provide feedback for bug reports and change requests.
Features
- 🎯 Visual element selection with hover overlay
- 💬 Floating popover for collecting user feedback
- ⌨️ Keyboard shortcuts (Cmd+Enter to submit, Escape to cancel)
- 🎨 Customizable colors, borders, and z-index
- 🔒 Origin validation for secure iframe communication
- ⚡ Lightweight with zero dependencies
- 🚀 Built for Next.js but works anywhere
Installation
npm install founder-grab
# or
bun add founder-grab
# or
yarn add founder-grabQuick Start (Next.js)
// app/layout.tsx
import { generateElementSelectorScript } from 'founder-grab';
import Script from 'next/script';
export default function RootLayout({ children }) {
return (
<html>
<head>
<Script id="element-selector" strategy="afterInteractive">
{generateElementSelectorScript()}
</Script>
</head>
<body>{children}</body>
</html>
);
}With Custom Configuration
<Script id="element-selector" strategy="afterInteractive">
{generateElementSelectorScript({
primaryColor: '#8b5cf6', // Purple (default)
borderWidth: '2px', // Border width (default)
zIndex: 999999, // Z-index for overlay (default)
allowedOrigins: [ // Optional: restrict which parents can communicate
'https://your-app.com'
]
})}
</Script>Usage
From Parent Application
Enable selection mode by sending a message to the iframe:
// In your parent application
const iframe = document.querySelector('iframe');
// Enable selection mode
iframe.contentWindow.postMessage({ type: 'ENABLE_SELECTION' }, '*');
// Disable selection mode
iframe.contentWindow.postMessage({ type: 'DISABLE_SELECTION' }, '*');Listening for Selected Elements
// In your parent application
window.addEventListener('message', (event) => {
if (event.data.type === 'ELEMENT_SELECTED') {
const { html, notes, selector, tagName } = event.data;
// Create a bug report or change request with this data
console.log('Element HTML:', html);
console.log('User notes:', notes);
console.log('CSS selector:', selector);
console.log('Tag name:', tagName);
}
});User Flow
- Parent application sends
ENABLE_SELECTIONmessage to iframe - User sees crosshair cursor and purple hover overlay on elements
- User clicks an element
- Floating popover appears with textarea for feedback
- User describes what needs to be changed
- User confirms (Cmd+Enter or clicks Confirm)
- Data is sent to parent application via
postMessage
API Reference
generateElementSelectorScript(config?)
Generates the inline script to inject into your page.
Parameters:
config(optional): Configuration objectprimaryColor(string): Color for overlay and buttons (default:'#8b5cf6')borderWidth(string): Width of selection border (default:'2px')zIndex(number): Z-index for overlay (default:999999)allowedOrigins(string[]): Allowed parent origins for security (default:[])
Returns: String containing the inline script
Message Types
Parent → Iframe
{ type: 'ENABLE_SELECTION' } // Enable selection mode
{ type: 'DISABLE_SELECTION' } // Disable selection modeIframe → Parent
{
type: 'ELEMENT_SELECTED',
html: string, // Element's outerHTML
notes: string, // User's feedback
selector: string, // CSS selector (e.g., '#id' or 'div.class')
tagName: string // Element tag name
}TypeScript Support
Full TypeScript definitions included:
import type {
ElementSelectorConfig,
ElementSelectedMessage,
MessageHandler
} from 'founder-grab';How It Works
This package injects a self-contained script that:
- Listens for
postMessageevents from parent window - Creates a hover overlay that follows the mouse in selection mode
- Captures clicks using capture phase event handling to prevent triggering buttons/links
- Shows a floating popover for collecting user feedback
- Sends element data back to parent via
postMessage
See IFRAME_COMMUNICATION.md for detailed technical documentation.
Security
- Origin validation can be enabled via
allowedOriginsconfig - All communication happens via
postMessageAPI - No data is sent to external servers
- Script is self-contained with no external dependencies
Browser Support
- Modern browsers (Chrome, Firefox, Safari, Edge)
- Requires ES6+ support
- No polyfills needed
License
MIT
Contributing
Issues and PRs welcome at github.com/your-org/founder-grab