get-containing-block
v1.0.4
Published
A lightweight TypeScript utility to find the containing block of a given HTML Element, following the [MDN Docs on Containing Block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block):
Readme
get-containing-block
A lightweight TypeScript utility to find the containing block of a given HTML Element, following the MDN Docs on Containing Block:
1. If the `position` property is `static`, `relative`, or `sticky`, the containing block is formed by the edge of the content box of the nearest ancestor element that is either **a block container** (such as an inline-block, block, or list-item element) or **establishes a formatting context** (such as a table container, flex container, grid container, or the block container itself).
2. If the `position` property is `absolute`, the containing block is formed by the edge of the padding box of the nearest ancestor element that has a `position `value other than `static` (`fixed`, `absolute`, `relative`, or `sticky`).
3. If the `position` property is `fixed`, the containing block is established by the **viewport** (in the case of continuous media) or the page area (in the case of paged media).
4. If the `position` property is `absolute` or `fixed`, the containing block may also be formed by the edge of the padding box of the nearest ancestor element that has any of the following:
- A `filter`, `backdrop-filter`, `transform`, `perspective`, `rotate`, `scale`, or `translate` value other than `none`.
- A `contain` value of `layout`, `paint`, `strict` or `content` (e.g., `contain: paint;`).
- A `container-type` value other than `normal`.
- A `will-change` value containing a property for which a non-initial value would form a containing block (e.g., `filter` or `transform`).
- A `content-visibility` value of `auto`.
Note: The containing block in which the root element (`<html>`) resides is a rectangle called the **initial containing block**. It has the dimensions of the viewport (for continuous media) or the page area (for paged media).Features
- Accurately identifies the containing block for elements with
fixed,absolute,relative,sticky, orstaticpositioning. - Handles edge cases like
transform,filter,perspective, andcontainproperties that create containing blocks. - Zero dependencies.
- Fully typed (TypeScript).
- ESM support.
Installation
npm install get-containing-blockUsage
import { getContainingBlock } from 'get-containing-block';
const element = document.querySelector('#my-element');
const { container } = getContainingBlock(element);
console.log('Containing block is:', container);Getting the Bounding Rect
You can optionally calculate the precise DOMRect of the containing block (handling padding-box vs content-box differences automatically).
const { container, rect } = getContainingBlock(element, true);
if (rect) {
console.log('Containing block rect:', rect);
}API
getContainingBlock(element, calcRect?)
Parameters:
element(HTMLElement): The element to find the containing block for.calcRect(boolean, optional): Iftrue, the result will include therectproperty. Defaults tofalse.
Returns:
- Object containing:
container(HTMLElement | null): The element serving as the containing block. Returnsnullif the containing block is the Initial Containing Block (Viewport).rect(DOMRect | undefined): The calculated bounding rectangle of the containing block. Only present ifcalcRectwastrue.
License
MIT