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-alignVerified import paths — ran on the pinned version, not inferred.
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.
Ensure `sourceNode.style.position = 'absolute';` and `sourceNode.style.left = '-9999px'; sourceNode.style.top = '-9999px';` are set before calling `domAlign`.
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.
To enable automatic viewport adjustment, set `overflow: { adjustX: true, adjustY: true }` in your `alignConfig`. Consider `alwaysByViewport: true` if adjustment should always prioritize the viewport.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';`.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.
No dependency data recorded yet.