Registry / web-framework / dom-align

dom-align

JSON →
library1.12.4jsnpmunverified

dom-align is a JavaScript library designed for flexible and precise alignment of HTML DOM elements. It enables positioning a 'source' element relative to a 'target' element, supporting various alignment points (e.g., top-left, center, bottom-right), pixel-based offsets, and percentage-based offsets relative to the element's dimensions. A key feature is its ability to automatically adjust the source element's position if it overflows the viewport or specified boundaries, ensuring visibility. It provides robust cross-browser support, compatible with modern browsers like Chrome and Firefox, as well as older versions like Internet Explorer 9+. The current stable version is 1.12.4. While it does not adhere to a strict time-based release cadence, updates are typically released as new features are added, existing issues are resolved, or performance improvements are implemented. The library ships with comprehensive TypeScript type definitions, facilitating its use in typed JavaScript and TypeScript projects.

npm install dom-align
INSTALL
IMPORT
SIG · DOM-ALIGN
D
dom-align
web-frameworkjavascriptv1.12.4
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.

domAlign
import domAlign from 'dom-align';
const domAlign = require('dom-align');
dom-align is primarily consumed as an ESM default import. Direct CommonJS `require` might lead to `domAlign is not a function` errors in certain module environments.
AlignConfig
import type { AlignConfig } from 'dom-align';
import { AlignConfig } from 'dom-align';
When importing types in TypeScript, always use `import type` to avoid bundling unused runtime code, especially for interface-only declarations.
AlignResult
import type { AlignResult } from 'dom-align';
The `domAlign` function returns an object with alignment results; its type is `AlignResult`. Import it for type-safe usage.

This quickstart demonstrates how to align a 'source' DOM element relative to a 'target' DOM element using `dom-align`. It sets up two basic divs, applies an alignment configuration that includes points, offsets, and overflow adjustments, and then performs the alignment, logging the result.

import domAlign from 'dom-align'; // Create a source and target node for alignment demonstration. // In a real application, these would be existing DOM elements. const sourceNode = document.createElement('div'); sourceNode.id = 'sourceNode'; sourceNode.style.cssText = 'position:absolute; left:-9999px; top:-9999px; width:100px; height:50px; background-color:blue; color:white; padding:5px;'; sourceNode.textContent = 'I am the source!'; document.body.appendChild(sourceNode); const targetNode = document.createElement('div'); targetNode.id = 'targetNode'; targetNode.style.cssText = 'position:relative; margin-top:150px; margin-left:200px; width:200px; height:100px; border:2px solid red; display:inline-block; padding:10px;'; targetNode.textContent = 'I am the target!'; document.body.appendChild(targetNode); // Define the alignment configuration. const alignConfig = { points: ['tl', 'br'], // Align top-left of sourceNode with bottom-right of targetNode offset: [5, 10], // Offset sourceNode by 5px in x, 10px in y after initial alignment targetOffset: ['-10%', '-5%'], // Offset targetNode by -10% of its width, -5% of its height overflow: { adjustX: true, adjustY: true }, // Auto-adjust position if sourceNode overflows viewport }; // Perform the alignment. The function returns an AlignResult object. const alignResult = domAlign(sourceNode, targetNode, alignConfig); console.log('Alignment successful:', alignResult.align); console.log('Adjustments made:', alignResult.overflow); // To clean up or re-align, you might remove elements or call domAlign again with different configs. // For demonstration, let's log the final position: setTimeout(() => { console.log(`Source node final position: left=${sourceNode.style.left}, top=${sourceNode.style.top}`); }, 0);
Debug
Known issues
gotchaThe `sourceNode` must be absolutely positioned and initially placed off-screen (e.g., `left: -9999px; top: -9999px;`) for `dom-align` to calculate its dimensions correctly before applying the alignment, especially when dealing with dynamic content or initial rendering.
fix
Ensure `sourceNode.style.position = 'absolute';` and `sourceNode.style.left = '-9999px'; sourceNode.style.top = '-9999px';` are set before calling `domAlign`.
affects: >=1.0.0
gotchaWhen using percentage values in `offset` or `targetOffset`, they are calculated relative to the *sourceNode's* or *targetNode's* dimensions, respectively. Incorrect assumptions about their reference frame can lead to unexpected positioning.
fix
Thoroughly test alignment configurations with percentage offsets and inspect the calculated `left` and `top` styles to ensure they match expectations. Refer to the API documentation for precise percentage calculation rules.
affects: >=1.0.0
gotchaThe `overflow` property's `adjustX` and `adjustY` flags determine if `dom-align` should automatically reposition the source node if it extends beyond the visible viewport. If these are not set to `true`, the source node might be clipped or hidden without adjustment.
fix
To enable automatic viewport adjustment, set `overflow: { adjustX: true, adjustY: true }` in your `alignConfig`. Consider `alwaysByViewport: true` if adjustment should always prioritize the viewport.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: domAlign is not a function
This error typically occurs when attempting to `require` or import `dom-align` in a CommonJS module context, but the default export is not handled correctly, or the module system is misconfigured for ESM.
fix
If using CommonJS, try `const domAlign = require('dom-align').default;` or ensure your build system (e.g., Webpack, Rollup) correctly transpiles ESM imports. For ESM, ensure you use `import domAlign from 'dom-align';`.
Cannot read properties of null (reading 'style') or similar 'Cannot read property X of undefined'
This error indicates that either the `source` or `target` HTMLElement passed to `domAlign` is `null` or `undefined`, meaning the element could not be found or was not rendered yet.
fix
Ensure that both `source` and `target` elements exist in the DOM and are valid `HTMLElement` instances before calling `domAlign`. Use `document.getElementById()`, `document.querySelector()`, or a React/Vue ref to reliably get the elements after they are mounted.
Upgrade
Version history
1.12.4latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
4 hits · last 30 days
node
4
Resources
dom-align — npm install dom-align · libregistry