Package Exports

css-box-model

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (css-box-model) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

CSS box model 📦

Get detailed CSS Box Model information about a HTMLElement

This library is useful for when you need to obtain detailed positioning information about an element. Any time you are using Element.getBoundingClientRect() you might want to consider using css-box-model instead to get more detailed information.

Usage

// @flow
import { getBox } from 'css-box-model';

const el: HTMLElement = document.getElementById('foo');
const box: BoxModel = getBox(el);

// profit

Installation

yarn add css-box-model

The CSS Box Model

Box type	Composition
Margin box	margin + border + padding + content
Border box	border + padding + content
Padding box	padding + content
Content box	content

------------------------------------
|              MARGIN              |  (marginBox)
|  ------------------------------  |
|  |           BORDER           |  |  (borderBox)
|  |  ------------------------  |  |
|  |  |       PADDING        |  |  |  (paddingBox)
|  |  |  ------------------  |  |  |
|  |  |  |    CONTENT     |  |  |  |  (contentBox)
|  |  |  |                |  |  |  |
|  |  |  |                |  |  |  |
|  |  |  |                |  |  |  |
|  |  |  ------------------  |  |  |
|  |  |                      |  |  |
|  |  ------------------------  |  |
|  |                            |  |
|  ------------------------------  |
|                                  |
| ---------------------------------|

This our returned BoxModel:

export type BoxModel = {|
  // content + padding + border + margin
  marginBox: Rect,
  // content + padding + border
  borderBox: Rect,
  // content + padding
  paddingBox: Rect,
  // content
  contentBox: Rect,
  // for your own consumption
  border: Spacing,
  padding: Spacing,
  margin: Spacing,
|};

// Supporting types

// This is an extension of DOMRect and ClientRect
export type Rect = {|
  // ClientRect
  top: number,
  right: number,
  bottom: number,
  left: number,
  width: number,
  height: number,
  // DOMRect
  x: number,
  y: number,
  // Rect
  center: Position,
|};

export type Position = {|
  x: number,
  y: number,
|};

export type Spacing = {
  top: number,
  right: number,
  bottom: number,
  left: number,
};

API

`getBox`

(el: HTMLElement) => BoxModel

Use getBox to return the box model for an element

`withScroll`

(original: BoxModel, scroll?: Position = getWindowScroll()) => BoxModel

This is useful if you want to know the box model for an element relative to a page

const el: HTMLElement = document.getElementById('app');
const box: BoxModel = getBox(el);
const withScroll: BoxModel = withScroll(box);

You are welcome to pass in your own scroll. By default we we use the window scroll:

const getWindowScroll = (): Position => ({
  x: window.pageXOffset,
  y: window.pageYOffset,
});

`calculateBox`

(borderBox: AnyRectType, styles: CSSStyleDeclaration) => BoxModel

This will do the box model calculations without needing to read from the DOM. This is useful if you have already got a ClientRect and CSSStyleDeclaration as we do not need to recompute it.

const el: HTMLElement = document.getElementById('app');
const borderBox: ClientRect = el.getBoundingClientRect();
const styles: CSSStyleDeclaration = window.getComputedStyles(el);

const box: BoxModel = calculateBox(borderBox, styles);

AnyRectType allows for simple interoperability with any rect type

type AnyRectType = ClientRect | DOMRect | Rect | Spacing;

`createBox`

({ borderBox, margin, border, padding }: CreateBoxArgs) => BoxModel

Allows you to create a BoxModel by passing in a Rect like shape and optionally your own margin, border and or padding.

type CreateBoxArgs = {|
  borderBox: AnyRectType,
  margin?: Spacing,
  border?: Spacing,
  padding?: Spacing,
|};

const borderBox: Spacing = {
  top: 10,
  right: 100,
  left: 20,
  bottom: 80,
};
const padding: Spacing = {
  top: 10,
  right: 20,
  left: 20,
  bottom: 10,
};

const box: BoxModel = createBox({ borderBox, padding });

`getRect`

(spacing: AnyRectType) => Rect

Given any Rect like shape, return a Rect

const spacing: Spacing = {
  top: 0,
  right: 100,
  bottom: 50,
  left: 50,
};

const rect: Rect = getRect(spacing);

console.log(rect);

/*
{
  top: 0,
  right: 100,
  bottom: 50,
  left: 50,
  width: 100,
  height: 50,
  x: 0,
  y: 0,
  center: { x: 50, y: 50 },
}
*/