tessl/npm-react-popper

Official library to use Popper on React projects

—

Pending

Overview

Eval results

Files

Reference Handling

Name: tessl/npm-react-popper
Author: tessl

Reference element handling functionality that marks DOM elements as reference points for positioning. The Reference component registers elements with the Manager context and provides render props for attaching refs to DOM elements.

Capabilities

Reference Component

Marks a DOM element as the reference point for positioning. Uses render props pattern to provide ref that must be attached to the target element.

/**
 * Marks an element as the reference point for positioning
 * @param children - Render prop function receiving ref to attach to DOM element
 * @param innerRef - Optional ref to the reference element for external access
 * @returns React element that registers reference with Manager context
 */
function Reference({ children, innerRef }: ReferenceProps): React.Node;

interface ReferenceProps {
  /** Render prop function that receives props for the reference element */
  children: (props: ReferenceChildrenProps) => React.ReactNode;
  /** Optional ref for external access to the reference element */
  innerRef?: React.Ref<any>;
}

interface ReferenceChildrenProps {
  /** Ref that must be attached to the DOM element that serves as reference */
  ref: React.Ref<any>;
}

Usage Examples:

import React from "react";
import { Manager, Reference, Popper } from "react-popper";

// Basic reference usage
function BasicReference() {
  return (
    <Manager>
      <Reference>
        {({ ref }) => (
          <button ref={ref} type="button">
            Reference Element
          </button>
        )}
      </Reference>
      {/* Popper component would go here */}
    </Manager>
  );
}

// Reference with external ref access
function ReferenceWithExternalRef() {
  const buttonRef = React.useRef(null);

  const handleClick = () => {
    if (buttonRef.current) {
      buttonRef.current.focus();
    }
  };

  return (
    <Manager>
      <Reference innerRef={buttonRef}>
        {({ ref }) => (
          <button ref={ref} onClick={handleClick}>
            Button with external ref
          </button>
        )}
      </Reference>
    </Manager>
  );
}

// Reference with complex elements
function ComplexReference() {
  return (
    <Manager>
      <Reference>
        {({ ref }) => (
          <div ref={ref} className="complex-reference">
            <img src="icon.png" alt="Icon" />
            <span>Complex Reference Content</span>
          </div>
        )}
      </Reference>
    </Manager>
  );
}

Ref Types

Reference handling supports both callback refs and ref objects:

/** Callback function for handling refs */
type RefHandler = (ref: HTMLElement | null) => void;

/** Ref object with current property */
type RefObject = { current?: HTMLElement | null };

/** Union type for React refs */
type Ref = RefHandler | RefObject;

Integration with Manager Context

The Reference component integrates with Manager context to:

Register reference elements: Automatically registers the ref'd element with Manager
Handle cleanup: Removes reference from context when component unmounts
Provide warnings: Warns in development if used outside Manager

Error Handling and Validation

The Reference component includes built-in safeguards:

Context validation: Warns if Reference is used outside of Manager component
Cleanup handling: Automatically cleans up refs on component unmount
Ref safety: Handles both callback and object refs safely

Best Practices

Always use within Manager:

// ✅ Correct
<Manager>
  <Reference>{({ ref }) => <button ref={ref}>Button</button>}</Reference>
</Manager>

// ❌ Incorrect - will show warning
<Reference>{({ ref }) => <button ref={ref}>Button</button>}</Reference>

Attach ref to actual DOM element:

// ✅ Correct - ref on DOM element
<Reference>
  {({ ref }) => <button ref={ref}>Button</button>}
</Reference>

// ❌ Incorrect - ref on React component
<Reference>
  {({ ref }) => <MyComponent ref={ref} />}
</Reference>

Use innerRef for external access:

// ✅ Good for external control
const myRef = useRef(null);
<Reference innerRef={myRef}>
  {({ ref }) => <button ref={ref}>Button</button>}
</Reference>

Handle dynamic references:

// ✅ Handle conditional rendering
<Reference>
  {({ ref }) => (
    <div>
      {showButton ? (
        <button ref={ref}>Dynamic Button</button>
      ) : (
        <span ref={ref}>Fallback Element</span>
      )}
    </div>
  )}
</Reference>

Install with Tessl CLI