get-containing-block

A lightweight TypeScript utility to find the containing block of a given HTML Element, following the CSS Containing Block specification.

Features

• Accurately identifies the containing block for elements with fixed, absolute, relative, sticky, or static positioning.
• Handles edge cases like transform, filter, perspective, and contain properties that create containing blocks.
• Zero dependencies.
• Fully typed (TypeScript).
• ESM support.

Installation

npm install get-containing-block

Usage

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): If true, the result will include the rect property. Defaults to false.

Returns:

• Object containing:
  • container (HTMLElement | null): The element serving as the containing block. Returns null if the containing block is the Initial Containing Block (Viewport).
  • rect (DOMRect | undefined): The calculated bounding rectangle of the containing block. Only present if calcRect was true.

License

MIT