Registry / web-framework / rc-align

rc-align

JSON →
library4.0.15jsnpmunverified

`rc-align` is a React UI component designed for precise element alignment within a web page, acting as a React wrapper for the `dom-align` library. It enables dynamic positioning of a child element relative to a target, supporting various target types including other DOM elements or specific page coordinates. The current stable version is 4.0.15, with a v5 pre-release indicating upcoming architectural changes. The library maintains a moderate release cadence, addressing bugs and adding features periodically. Key differentiators include its robust underlying `dom-align` logic, support for realigning on window resize, and a focus on providing a declarative React interface for complex positioning scenarios. It ships with TypeScript types for improved developer experience and integrates seamlessly into React applications requiring dynamic UI positioning.

npm install rc-align
INSTALL
IMPORT
SIG · RC-ALIGN
R
rc-align
web-frameworkjavascriptv4.0.15
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

Align
import Align from 'rc-align';
import { Align } from 'rc-align';
The primary `Align` component is a default export.
Align
const Align = require('rc-align');
const { Align } = require('rc-align');
CommonJS usage for Node.js environments or older bundlers. `Align` is the default export.
AlignProps
import type { AlignProps } from 'rc-align';
Importing TypeScript types for the component's props.

This quickstart demonstrates how to use `rc-align` to position a 'source' React element relative to a 'target' DOM element. It utilizes `useRef` for element references, configures alignment points, an offset, and enables realignment on window resize.

import React from 'react'; import ReactDOM from 'react-dom'; import Align from 'rc-align'; const MyAlignedComponent: React.FC = () => { const targetRef = React.useRef<HTMLDivElement>(null); const sourceRef = React.useRef<HTMLDivElement>(null); // In a real application, ensure the target is mounted before alignment logic runs. // This simple example assumes static target. const getTarget = () => targetRef.current; return ( <div style={{ padding: '50px', position: 'relative', minHeight: '300px' }}> <div ref={targetRef} style={{ width: '100px', height: '100px', border: '2px solid blue', position: 'absolute', top: '150px', left: '150px', display: 'flex', alignItems: 'center', justifyContent: 'center', background: '#e0f7fa' }} > Target Element </div> <Align target={getTarget} align={{ points: ['tl', 'bl'], // Align top-left of source to bottom-left of target offset: [0, 10], // Offset by 10px down overflow: { adjustX: true, adjustY: true } }} monitorWindowResize={true} onAlign={(sourceElement, alignConfig) => { console.log('Aligned!', sourceElement, alignConfig); }} > <div ref={sourceRef} style={{ width: '120px', height: '50px', border: '2px solid red', background: '#ffebee', zIndex: 100, // Ensure it's above other elements if positioned absolutely display: 'flex', alignItems: 'center', justifyContent: 'center' }} > Source Element </div> </Align> </div> ); }; const rootElement = document.getElementById('root'); if (rootElement) { ReactDOM.render(<MyAlignedComponent />, rootElement); } else { console.error("Root element not found. Please ensure an element with id 'root' exists in your HTML."); }
Debug
Known issues
breakingVersion 5.0.0-0 and newer replace the underlying alignment library from `dom-align` to `@rc-component/dom-align`. This is a significant internal change that could affect advanced users who were interacting with the underlying library or expecting its specific behavior.
fix
While `rc-align` aims to abstract this change, review your `align` configuration objects and any direct usage of `dom-align` if you are upgrading to v5.
affects: >=5.0.0-0
gotchaOlder versions (prior to 4.0.13) may exhibit unexpected behavior or compatibility issues when used within React's Strict Mode.
fix
Upgrade to `rc-align` version 4.0.13 or newer to ensure better compatibility and stability in React Strict Mode.
affects: <4.0.13
deprecatedSome internal APIs or passed-through configurations were modified in version 4.0.10, particularly those related to `dom-align`. Using older API patterns might lead to incorrect alignment or warnings.
fix
Consult the `rc-align` and `dom-align` documentation for specific API changes and update your `align` prop configuration objects accordingly.
affects: <4.0.10
gotchaThe `onAlign` callback might not always trigger reliably or might receive outdated position data in certain edge cases (e.g., when `forceAlign` is used or if the alignment result is empty) in versions prior to 4.0.9.
fix
Upgrade to `rc-align` version 4.0.9 or newer to resolve issues with `onAlign` callback consistency and accuracy.
affects: <4.0.9
gotchaServer-Side Rendering (SSR) might encounter issues in older versions due to unnecessary element checks being performed in the server environment.
fix
Upgrade to `rc-align` version 4.0.14 or later to fix SSR rendering problems related to improper element validation.
affects: <4.0.14
Errors
Common errors & fixes
Error: `target` must be an HTMLElement or a point object, but got null/undefined
The `target` prop function returned `null` or `undefined` because the target DOM element was not yet mounted or was unmounted before alignment.
fix
Ensure the target element referenced by `targetRef.current` (or similar) is fully mounted and available in the DOM when `rc-align` attempts to perform alignment. You might need to add a conditional render or a `useEffect` hook to defer alignment until the target is ready.
onAlign callback not firing or receiving stale data
Issues with `onAlign` triggering logic or data consistency were present in older versions, especially in complex scenarios or when `align` props changed frequently.
fix
Upgrade to `rc-align` v4.0.9 or later. Also, ensure that the `align` prop is a stable object or memoized if it's not strictly changing, to avoid unnecessary re-renders and re-alignments.
React component not aligning correctly after window resize
The `monitorWindowResize` prop was not enabled, preventing the component from re-evaluating its position when the browser window dimensions change.
fix
Set the `monitorWindowResize` prop to `true` on the `Align` component: `<Align monitorWindowResize={true} ... />`.
Upgrade
Version history
4.0.15latest on npm
Audit
Dependencies
reactrequiredPeer dependency for React component functionality.
react-domrequiredPeer dependency for DOM rendering within React applications.
Agent activity
4 hits · last 30 days
node
4
Resources
rc-align — npm install rc-align · libregistry