{"id":10754,"library":"dom-align","title":"DOM Align","description":"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.","status":"active","version":"1.12.4","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/yiminghe/dom-align","tags":["javascript","dom","align","typescript"],"install":[{"cmd":"npm install dom-align","lang":"bash","label":"npm"},{"cmd":"yarn add dom-align","lang":"bash","label":"yarn"},{"cmd":"pnpm add dom-align","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const domAlign = require('dom-align');","symbol":"domAlign","correct":"import domAlign from 'dom-align';"},{"note":"When importing types in TypeScript, always use `import type` to avoid bundling unused runtime code, especially for interface-only declarations.","wrong":"import { AlignConfig } from 'dom-align';","symbol":"AlignConfig","correct":"import type { AlignConfig } from 'dom-align';"},{"note":"The `domAlign` function returns an object with alignment results; its type is `AlignResult`. Import it for type-safe usage.","symbol":"AlignResult","correct":"import type { AlignResult } from 'dom-align';"}],"quickstart":{"code":"import domAlign from 'dom-align';\n\n// Create a source and target node for alignment demonstration.\n// In a real application, these would be existing DOM elements.\nconst sourceNode = document.createElement('div');\nsourceNode.id = 'sourceNode';\nsourceNode.style.cssText = 'position:absolute; left:-9999px; top:-9999px; width:100px; height:50px; background-color:blue; color:white; padding:5px;';\nsourceNode.textContent = 'I am the source!';\ndocument.body.appendChild(sourceNode);\n\nconst targetNode = document.createElement('div');\ntargetNode.id = 'targetNode';\ntargetNode.style.cssText = 'position:relative; margin-top:150px; margin-left:200px; width:200px; height:100px; border:2px solid red; display:inline-block; padding:10px;';\ntargetNode.textContent = 'I am the target!';\ndocument.body.appendChild(targetNode);\n\n// Define the alignment configuration.\nconst alignConfig = {\n  points: ['tl', 'br'], // Align top-left of sourceNode with bottom-right of targetNode\n  offset: [5, 10],       // Offset sourceNode by 5px in x, 10px in y after initial alignment\n  targetOffset: ['-10%', '-5%'], // Offset targetNode by -10% of its width, -5% of its height\n  overflow: { adjustX: true, adjustY: true }, // Auto-adjust position if sourceNode overflows viewport\n};\n\n// Perform the alignment. The function returns an AlignResult object.\nconst alignResult = domAlign(sourceNode, targetNode, alignConfig);\n\nconsole.log('Alignment successful:', alignResult.align);\nconsole.log('Adjustments made:', alignResult.overflow);\n\n// To clean up or re-align, you might remove elements or call domAlign again with different configs.\n// For demonstration, let's log the final position:\nsetTimeout(() => {\n  console.log(`Source node final position: left=${sourceNode.style.left}, top=${sourceNode.style.top}`);\n}, 0);\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Ensure `sourceNode.style.position = 'absolute';` and `sourceNode.style.left = '-9999px'; sourceNode.style.top = '-9999px';` are set before calling `domAlign`.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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';`.","cause":"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.","error":"TypeError: domAlign is not a function"},{"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.","cause":"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.","error":"Cannot read properties of null (reading 'style') or similar 'Cannot read property X of undefined'"}],"ecosystem":"npm"}