React Archer

Common errors

• Property 'refreshScreen' does not exist on type 'ArcherContainer | null'.

  cause Attempting to call the `refreshScreen` method on an `ArcherContainer` ref without proper TypeScript typing or before the ref is assigned.
  fix Ensure your ref is correctly typed using `ArcherContainerRef` and checked for `null` before use: `const archerRef = useRef<ArcherContainerRef>(null); archerRef.current?.refreshScreen();`

• ReferenceError: document is not defined

  cause `react-archer` attempting to access DOM-specific objects (like `document`) during a server-side rendering (SSR) environment before the browser's `window` or `document` objects are available.
  fix Ensure you are using `react-archer@4.2.2` or newer which includes SSR fixes. If issues persist, consider dynamically importing `react-archer` components only on the client-side or using a conditional rendering approach for SSR.

• Arrows are not appearing or are stuck at position (0,0).

  cause This can be caused by incorrect element IDs, elements not being registered correctly, or issues with initial rendering logic within `ArcherContainer`.
  fix Verify that all `id` props on `ArcherElement`s are unique and valid strings. Ensure all `ArcherElement`s are descendants of an `ArcherContainer`. Update to `react-archer@4.2.0` or later for fixes related to element registration and refreshing. Check browser console for related errors.

Warnings

• breaking Version 4.0.0 completely dropped Flow type support and migrated the codebase to TypeScript. The internal implementation was also refactored to use React Hooks instead of class components.
  Fix: Users relying on Flow types must either remain on `react-archer@3.x` or migrate their project to TypeScript.
• breaking Version 4.1.0 introduced changes to arrow ID encoding and how arrow markers are displayed, specifically by not using the full URL. This change may break arrow rendering on some older Safari browser versions, while fixing issues with URLs containing hash characters (`#`).
  Fix: Ensure target user environments use modern Safari versions. For applications with `#` in URLs, this update resolves previous issues.
• gotcha Earlier versions of `react-archer` (pre-4.2.1) had known issues with Server-Side Rendering (SSR), leading to arrows not being displayed or runtime warnings.
  Fix: Update to `react-archer@4.2.2` or later to leverage bug fixes specifically addressing SSR compatibility and rendering issues.
• gotcha Prior to version 4.2.0, there were reported bugs regarding element registration and refreshing, leading to arrows not updating their positions correctly or not drawing at all.
  Fix: Update to `react-archer@4.2.0` or later. For situations requiring manual control, access the `refreshScreen` method via the `ArcherContainer` ref, e.g., `archerRef.current?.refreshScreen()`.
• gotcha TypeScript users attempting to use `ref` with `ArcherContainer` components prior to v4.2.3 might have experienced improper type inference or errors.
  Fix: Update to `react-archer@4.2.3` or later and use the exported `ArcherContainerRef` type, e.g., `const archerRef = useRef<ArcherContainerRef>(null);`.

Install

• npm install react-archer npm
• yarn add react-archer yarn
• pnpm add react-archer pnpm

Imports

• ArcherContainer
  wrong:

  const ArcherContainer = require('react-archer').ArcherContainer;

  correct:

  import { ArcherContainer } from 'react-archer';

  Prefer named imports. CommonJS `require` syntax is not recommended, especially if your project is ESM-first.
• ArcherElement
  wrong:

  import ArcherElement from 'react-archer/ArcherElement';

  correct:

  import { ArcherElement } from 'react-archer';

  ArcherElement is a named export from the main package entry point, not a default export or submodule import.
• ArcherContainerRef
  wrong:

  import { ArcherContainerRef } from 'react-archer';

  correct:

  import type { ArcherContainerRef } from 'react-archer';

  This is a TypeScript type for the ref object. Use `import type` to avoid bundling it at runtime. Available since v4.2.3.

Quickstart

Demonstrates how to set up `ArcherContainer` and `ArcherElement` to draw multiple arrows between React components with custom styling, labels, and anchor points.

import { ArcherContainer, ArcherElement } from 'react-archer';
import React from 'react';

const rootStyle = { display: 'flex', justifyContent: 'center' };
const rowStyle = { margin: '200px 0', display: 'flex', justifyContent: 'space-between' };
const boxStyle = { padding: '10px', border: '1px solid black' };

const App = () => {
  return (
    <div style={{ height: '500px', margin: '50px' }}>
      <ArcherContainer strokeColor="red">
        <div style={rootStyle}>
          <ArcherElement
            id="root"
            relations={[
              {
                targetId: 'element2',
                targetAnchor: 'top',
                sourceAnchor: 'bottom',
                style: { strokeDasharray: '5,5' }
              }
            ]}
          >
            <div style={boxStyle}>Root</div>
          </ArcherElement>
        </div>

        <div style={rowStyle}>
          <ArcherElement
            id="element2"
            relations={[
              {
                targetId: 'element3',
                targetAnchor: 'left',
                sourceAnchor: 'right',
                style: { strokeColor: 'blue', strokeWidth: 1 },
                label: <div style={{ marginTop: '-20px' }}>Arrow 2</div>
              }
            ]}
          >
            <div style={boxStyle}>Element 2</div>
          </ArcherElement>

          <ArcherElement id="element3">
            <div style={boxStyle}>Element 3</div>
          </ArcherElement>

          <ArcherElement
            id="element4"
            relations={[
              {
                targetId: 'root',
                targetAnchor: 'right',
                sourceAnchor: 'left',
                label: 'Arrow 3'
              }
            ]}
          >
            <div style={boxStyle}>Element 4</div>
          </ArcherElement>
        </div>
      </ArcherContainer>
    </div>
  );
};

export default App;