ReactGrabAPI

Complete API reference for the ReactGrabAPI interface

Overview

The ReactGrabAPI interface provides programmatic control over React Grab. It’s returned by the init() function and includes methods to activate/deactivate React Grab, manage state, register plugins, and more.

Type Definition

interface ReactGrabAPI {
  activate: () => void;
  deactivate: () => void;
  toggle: () => void;
  comment: () => void;
  isActive: () => boolean;
  isEnabled: () => boolean;
  setEnabled: (enabled: boolean) => void;
  getToolbarState: () => ToolbarState | null;
  setToolbarState: (state: Partial<ToolbarState>) => void;
  onToolbarStateChange: (callback: (state: ToolbarState) => void) => () => void;
  dispose: () => void;
  copyElement: (elements: Element | Element[]) => Promise<boolean>;
  getSource: (element: Element) => Promise<SourceInfo | null>;
  getStackContext: (element: Element) => Promise<string>;
  getState: () => ReactGrabState;
  setOptions: (options: SettableOptions) => void;
  registerPlugin: (plugin: Plugin) => void;
  unregisterPlugin: (name: string) => void;
  getPlugins: () => string[];
  getDisplayName: (element: Element) => string | null;
}

Methods

activate()

Activates React Grab, allowing element selection.

api.activate(): void

Example:

const api = init();
api.activate();

Notes:

• Only activates if React Grab is currently enabled
• Clears any pending comment mode
• Does nothing if already active

---

deactivate()

Deactivates React Grab, stopping element selection.

api.deactivate(): void

Example:

const api = init();
api.deactivate();

Notes:

• Works even if currently in a copying state
• Cleans up all active selections and overlays
• Restores previously focused elements

---

toggle()

Toggles React Grab between active and inactive states.

api.toggle(): void

Example:

const api = init();
api.toggle(); // Activates
api.toggle(); // Deactivates

---

comment()

Activates comment mode, which allows adding a text prompt to copied elements.

api.comment(): void

Example:

const api = init();
api.comment();
// Now when you select an element, you'll be prompted for a comment

Notes:

• If already in comment mode and active, deactivates React Grab
• Sets pending comment mode flag if not already active

---

isActive()

Checks if React Grab is currently active.

api.isActive(): boolean

Example:

const api = init();
if (api.isActive()) {
  console.log('React Grab is active');
}

Returns:

• true if React Grab is active and element selection is enabled
• false otherwise

---

isEnabled()

Checks if React Grab is enabled.

api.isEnabled(): boolean

Example:

const api = init();
if (api.isEnabled()) {
  console.log('React Grab is enabled');
}

Returns:

• true if React Grab is enabled
• false if disabled

Notes:

• Enabled state is separate from active state
• When disabled, React Grab cannot be activated

---

setEnabled()

Enables or disables React Grab.

api.setEnabled(enabled: boolean): void

enabled · boolean · required

Whether to enable or disable React Grab

Example:

const api = init();
api.setEnabled(false); // Disable React Grab
api.setEnabled(true);  // Enable React Grab

Notes:

• Disabling React Grab also deactivates it if currently active
• The enabled state persists in toolbar state

---

getToolbarState()

Gets the current toolbar state.

api.getToolbarState(): ToolbarState | null

Returns:

interface ToolbarState {
  edge: 'top' | 'bottom' | 'left' | 'right';
  ratio: number; // 0-1, position along the edge
  collapsed: boolean;
  enabled: boolean;
}

Example:

const api = init();
const state = api.getToolbarState();
console.log(`Toolbar is on ${state?.edge} edge`);

---

setToolbarState()

Updates the toolbar state.

api.setToolbarState(state: Partial<ToolbarState>): void

state · Partial<ToolbarState> · required

Partial toolbar state to update

Example:

const api = init();
api.setToolbarState({
  edge: 'top',
  collapsed: true
});

Notes:

• Only provided properties are updated
• Changes are saved to localStorage
• Triggers toolbar state change callbacks

---

onToolbarStateChange()

Subscribes to toolbar state changes.

api.onToolbarStateChange(callback: (state: ToolbarState) => void): () => void

callback · (state: ToolbarState) => void · required

Function to call when toolbar state changes

Returns:

• Unsubscribe function

Example:

const api = init();
const unsubscribe = api.onToolbarStateChange((state) => {
  console.log('Toolbar state changed:', state);
});

// Later: unsubscribe()

---

dispose()

Cleans up all React Grab resources, event listeners, and state.

api.dispose(): void

Example:

const api = init();
// ... use React Grab ...
api.dispose(); // Clean up when done

Notes:

• Removes all event listeners
• Clears all timers and intervals
• Removes overlay elements from DOM
• After calling dispose(), a new init() call will work

---

copyElement()

Programmatically copies one or more elements.

api.copyElement(elements: Element | Element[]): Promise<boolean>

elements · Element | Element[] · required

Element or array of elements to copy

Returns:

• Promise<boolean> - Resolves to true if copy succeeded, false otherwise

Example:

const api = init();
const button = document.querySelector('button');
if (button) {
  const success = await api.copyElement(button);
  console.log(success ? 'Copied!' : 'Failed');
}

Example - Multiple Elements:

const api = init();
const items = Array.from(document.querySelectorAll('.item'));
const success = await api.copyElement(items);

---

getSource()

Gets source information for an element.

api.getSource(element: Element): Promise<SourceInfo | null>

element · Element · required

The element to get source info for

Returns:

interface SourceInfo {
  filePath: string;
  lineNumber: number | null;
  componentName: string | null;
}

Example:

const api = init();
const button = document.querySelector('button');
if (button) {
  const source = await api.getSource(button);
  if (source) {
    console.log(`Component: ${source.componentName}`);
    console.log(`File: ${source.filePath}:${source.lineNumber}`);
  }
}

Notes:

• Returns null if source information cannot be determined
• Requires React DevTools fiber information to be available

---

getStackContext()

Gets the stack context for an element.

api.getStackContext(element: Element): Promise<string>

element · Element · required

The element to get stack context for

Returns:

• Promise<string> - A formatted string with the element’s component stack

Example:

const api = init();
const div = document.querySelector('.container');
if (div) {
  const context = await api.getStackContext(div);
  console.log(context);
  // Output: "App > Layout > Container > div"
}

---

getState()

Gets the current React Grab state.

api.getState(): ReactGrabState

Returns:

interface ReactGrabState {
  isActive: boolean;
  isDragging: boolean;
  isCopying: boolean;
  isPromptMode: boolean;
  isCrosshairVisible: boolean;
  isSelectionBoxVisible: boolean;
  isDragBoxVisible: boolean;
  targetElement: Element | null;
  dragBounds: DragRect | null;
  grabbedBoxes: Array<{
    id: string;
    bounds: OverlayBounds;
    createdAt: number;
  }>;
  labelInstances: Array<{
    id: string;
    status: SelectionLabelStatus;
    tagName: string;
    componentName?: string;
    createdAt: number;
  }>;
  selectionFilePath: string | null;
  toolbarState: ToolbarState | null;
}

Example:

const api = init();
const state = api.getState();
if (state.isActive && state.targetElement) {
  console.log('Currently hovering:', state.targetElement);
}

---

setOptions()

Updates React Grab options after initialization.

api.setOptions(options: SettableOptions): void

options · SettableOptions · required

Options to update. Same as Options but without the enabled property.

Example:

const api = init();
api.setOptions({
  activationMode: 'hold',
  keyHoldDuration: 300,
  maxContextLines: 5
});

Notes:

• Cannot change the enabled option - use setEnabled() instead
• Changes take effect immediately
• Affects all registered plugins

---

registerPlugin()

Registers a new plugin with React Grab.

api.registerPlugin(plugin: Plugin): void

plugin · Plugin · required

The plugin to register

Example:

import { init } from 'react-grab';

const api = init();

api.registerPlugin({
  name: 'my-plugin',
  setup: (api, hooks) => {
    return {
      actions: [{
        id: 'custom-action',
        label: 'Custom Action',
        target: 'context-menu',
        onAction: (context) => {
          console.log('Custom action!', context.element);
        }
      }]
    };
  }
});

Notes:

• Plugins can add custom actions, hooks, and theme overrides
• See Plugin API for details

---

unregisterPlugin()

Unregisters a plugin by name.

api.unregisterPlugin(name: string): void

name · string · required

The name of the plugin to unregister

Example:

const api = init();
api.unregisterPlugin('my-plugin');

Notes:

• Built-in plugins cannot be unregistered
• Plugin cleanup methods are called automatically

---

getPlugins()

Gets a list of registered plugin names.

api.getPlugins(): string[]

Returns:

• string[] - Array of plugin names

Example:

const api = init();
const plugins = api.getPlugins();
console.log('Registered plugins:', plugins);
// Output: ['copy', 'comment', 'copyHtml', 'copyStyles', 'open', 'my-plugin']

---

getDisplayName()

Gets the display name (component name or tag name) for an element.

api.getDisplayName(element: Element): string | null

element · Element · required

The element to get the display name for

Returns:

• Component name if available (e.g., 'Button', 'MyComponent')
• Tag name if no component name found (e.g., 'div', 'button')
• null if neither can be determined

Example:

const api = init();
const button = document.querySelector('button');
if (button) {
  const name = api.getDisplayName(button);
  console.log('Display name:', name);
  // Output: "Button" or "button"
}

Usage Example

Here’s a comprehensive example using multiple API methods:

import { init } from 'react-grab';

// Initialize with custom options
const api = init({
  activationMode: 'toggle',
  maxContextLines: 5
});

// Subscribe to state changes
const unsubscribe = api.onToolbarStateChange((state) => {
  console.log('Toolbar moved to:', state.edge);
});

// Programmatically copy an element
const copyButton = async () => {
  const button = document.querySelector('.my-button');
  if (button) {
    const success = await api.copyElement(button);
    if (success) {
      const source = await api.getSource(button);
      console.log('Copied from:', source?.filePath);
    }
  }
};

// Check state
const checkState = () => {
  const state = api.getState();
  console.log('Active:', state.isActive);
  console.log('Target:', api.getDisplayName(state.targetElement));
};

// Cleanup when done
window.addEventListener('beforeunload', () => {
  unsubscribe();
  api.dispose();
});