child-locator

A React Hook for detecting child components at specific XY coordinates within a container element.

What is this?

If you're hesitant to manipulate delicate Observers to retrieve elements at specific positions displayed in the browser using React, the child-locator package might be useful.

This package identifies elements within a specified visible area of the page and makes it easy to retrieve the information held by those elements. Since it's implemented using callback handlers, it can detect changes even when the layout shifts and elements change.

The detection position is not limited to absolute coordinates; it can also use various CSS units, enabling stable position detection for responsive design pages.

Features:

• XY Coordinate Detection: Precisely locate child components at specified coordinates
• CSS Unit Support: Coordinate values support px (number), %, vw, vh, rem, em (string) and other CSS units
• Real-time Monitoring: Automatically detects changes in child elements using MutationObserver, ResizeObserver, and IntersectionObserver

Installation

npm install child-locator

Basic Usage

1. Setup Provider

First, setup your app with ChildLocatorProvider:

import React from 'react';
import { ChildLocatorProvider } from 'child-locator';
import App from './App';

function Root() {
  return (
    <ChildLocatorProvider>
      <App />
    </ChildLocatorProvider>
  );
}

2. Create Trackable Components

Use withChildLocator to make components trackable:

import React from 'react';
import { withChildLocator } from 'child-locator';

type BaseChildItemProps = {
  id: number;
  children: React.ReactNode;
};

// Base (simple) component.
const BaseChildItem = ({ id, children }: BaseChildItemProps) => {
  return <div data-testid={`child-${id}`}>{children}</div>;
};

// withChildLocator will inject the DOM anchor automatically.
const ChildItem = withChildLocator(BaseChildItem);

When a component does not expose a ref, withChildLocator automatically injects an invisible wrapper so that the element can still be tracked. See the dedicated withChildLocator section below for that pattern.

3. Use Detection Hook

Use useLocator to detect components at specific coordinates:

import React, { useRef } from 'react';
import { useLocator } from 'child-locator';
import type { DetectedComponent } from 'child-locator';

const ParentComponent = () => {
  // Makes refer the container
  const containerRef = useRef<HTMLDivElement>(null);

  useLocator(containerRef, {
    // Detection coordinates: CSS units supported: px, %, vw, vh, rem, em
    offset: { x: '50%', y: '30%' },
    // Detected callback:
    onDetect: (component: DetectedComponent) => {
      if (component.element) {
        console.log('Detected element:', component.element);
        console.log('Distance from target:', component.distanceFromOffset);
        console.log(
          'Component metadata:',
          component.component?.props._tetherMetadata
        );
      } else {
        console.log('No child elements at target coordinates');
      }
    },
    enabled: true,
  });

  // Place detection target items into the container
  return (
    <div
      ref={containerRef}
      style={{ width: 400, height: 300, position: 'relative' }}
    >
      <ChildItem id={1} tetherMetadata={{ type: 'grid-item', row: 1, col: 1 }}>
        Item 1
      </ChildItem>
      <ChildItem id={2} tetherMetadata={{ type: 'grid-item', row: 1, col: 2 }}>
        Item 2
      </ChildItem>
      <ChildItem id={3} tetherMetadata={{ type: 'grid-item', row: 2, col: 1 }}>
        Item 3
      </ChildItem>
    </div>
  );
};

Documentation

See repository douments for detail.

License

Under MIT.