{"id":11627,"library":"rc-align","title":"React Alignment Component","description":"`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.","status":"active","version":"4.0.15","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/react-component/align","tags":["javascript","react","react-component","react-align","align","typescript"],"install":[{"cmd":"npm install rc-align","lang":"bash","label":"npm"},{"cmd":"yarn add rc-align","lang":"bash","label":"yarn"},{"cmd":"pnpm add rc-align","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for React component functionality.","package":"react","optional":false},{"reason":"Peer dependency for DOM rendering within React applications.","package":"react-dom","optional":false}],"imports":[{"note":"The primary `Align` component is a default export.","wrong":"import { Align } from 'rc-align';","symbol":"Align","correct":"import Align from 'rc-align';"},{"note":"CommonJS usage for Node.js environments or older bundlers. `Align` is the default export.","wrong":"const { Align } = require('rc-align');","symbol":"Align","correct":"const Align = require('rc-align');"},{"note":"Importing TypeScript types for the component's props.","symbol":"AlignProps","correct":"import type { AlignProps } from 'rc-align';"}],"quickstart":{"code":"import React from 'react';\nimport ReactDOM from 'react-dom';\nimport Align from 'rc-align';\n\nconst MyAlignedComponent: React.FC = () => {\n  const targetRef = React.useRef<HTMLDivElement>(null);\n  const sourceRef = React.useRef<HTMLDivElement>(null);\n\n  // In a real application, ensure the target is mounted before alignment logic runs.\n  // This simple example assumes static target.\n\n  const getTarget = () => targetRef.current;\n\n  return (\n    <div style={{ padding: '50px', position: 'relative', minHeight: '300px' }}>\n      <div\n        ref={targetRef}\n        style={{\n          width: '100px',\n          height: '100px',\n          border: '2px solid blue',\n          position: 'absolute',\n          top: '150px',\n          left: '150px',\n          display: 'flex',\n          alignItems: 'center',\n          justifyContent: 'center',\n          background: '#e0f7fa'\n        }}\n      >\n        Target Element\n      </div>\n\n      <Align\n        target={getTarget}\n        align={{\n          points: ['tl', 'bl'], // Align top-left of source to bottom-left of target\n          offset: [0, 10], // Offset by 10px down\n          overflow: {\n            adjustX: true,\n            adjustY: true\n          }\n        }}\n        monitorWindowResize={true}\n        onAlign={(sourceElement, alignConfig) => {\n          console.log('Aligned!', sourceElement, alignConfig);\n        }}\n      >\n        <div\n          ref={sourceRef}\n          style={{\n            width: '120px',\n            height: '50px',\n            border: '2px solid red',\n            background: '#ffebee',\n            zIndex: 100, // Ensure it's above other elements if positioned absolutely\n            display: 'flex',\n            alignItems: 'center',\n            justifyContent: 'center'\n          }}\n        >\n          Source Element\n        </div>\n      </Align>\n    </div>\n  );\n};\n\nconst rootElement = document.getElementById('root');\nif (rootElement) {\n  ReactDOM.render(<MyAlignedComponent />, rootElement);\n} else {\n  console.error(\"Root element not found. Please ensure an element with id 'root' exists in your HTML.\");\n}","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=5.0.0-0"},{"fix":"Upgrade to `rc-align` version 4.0.13 or newer to ensure better compatibility and stability in React Strict Mode.","message":"Older versions (prior to 4.0.13) may exhibit unexpected behavior or compatibility issues when used within React's Strict Mode.","severity":"gotcha","affected_versions":"<4.0.13"},{"fix":"Consult the `rc-align` and `dom-align` documentation for specific API changes and update your `align` prop configuration objects accordingly.","message":"Some 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.","severity":"deprecated","affected_versions":"<4.0.10"},{"fix":"Upgrade to `rc-align` version 4.0.9 or newer to resolve issues with `onAlign` callback consistency and accuracy.","message":"The `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.","severity":"gotcha","affected_versions":"<4.0.9"},{"fix":"Upgrade to `rc-align` version 4.0.14 or later to fix SSR rendering problems related to improper element validation.","message":"Server-Side Rendering (SSR) might encounter issues in older versions due to unnecessary element checks being performed in the server environment.","severity":"gotcha","affected_versions":"<4.0.14"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The `target` prop function returned `null` or `undefined` because the target DOM element was not yet mounted or was unmounted before alignment.","error":"Error: `target` must be an HTMLElement or a point object, but got null/undefined"},{"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.","cause":"Issues with `onAlign` triggering logic or data consistency were present in older versions, especially in complex scenarios or when `align` props changed frequently.","error":"onAlign callback not firing or receiving stale data"},{"fix":"Set the `monitorWindowResize` prop to `true` on the `Align` component: `<Align monitorWindowResize={true} ... />`.","cause":"The `monitorWindowResize` prop was not enabled, preventing the component from re-evaluating its position when the browser window dimensions change.","error":"React component not aligning correctly after window resize"}],"ecosystem":"npm"}