react-archer

library4.4.0jsnpmunverified

React Archer is a JavaScript library for drawing dynamic, configurable SVG arrows between any DOM elements within a React application. It is currently at version 4.4.0 and maintains a consistent release cadence, with multiple feature and bugfix releases within recent months, indicating active development. Its primary utility lies in simplifying the visualization of relationships or flows between disparate UI components. Key features include customizable arrow styles (color, width, dash array, curves/angles), support for start/end markers, and the ability to update arrow positions automatically when elements move or resize. It achieves this by managing an SVG layer over your React components, dynamically calculating coordinates based on element anchors. The library supports server-side rendering and provides TypeScript types, making it robust for modern React development.

web-framework

npm install react-archer

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-ARCHER

react-archer

web-frameworkjavascriptv4.4.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ArcherContainer

✓ import { ArcherContainer } from 'react-archer';

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

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

ArcherElement

✓ import { ArcherElement } from 'react-archer';

✗ import ArcherElement from 'react-archer/ArcherElement';

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

ArcherContainerRef

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

✗ import { 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.

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;

Debug

Known issues

breakingVersion 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.

affects: >=4.0.0

breakingVersion 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.

affects: >=4.1.0

gotchaEarlier 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.

affects: 4.0.0 - 4.2.0

gotchaPrior 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()`.

affects: <4.2.0

gotchaTypeScript 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);`.

affects: <4.2.3

Errors

Common errors & fixes

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

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

`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).

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.

Upgrade

Version history

4.4.0latest on npm

Audit

Dependencies

reactrequiredCore React functionality is required for components and hooks.

@types/reactoptionalProvides TypeScript types for React components, essential for a fully typed development experience.

prop-typesoptionalUsed for runtime prop type validation, though less common in TypeScript-first projects.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/pierpo/react-archer ↗

packagehttps://www.npmjs.com/package/react-archer ↗

homepagehttps://react-archer.io ↗