{"id":13447101,"url":"https://github.com/alexreardon/css-box-model","last_synced_at":"2025-05-16T13:05:34.219Z","repository":{"id":46937390,"uuid":"129664139","full_name":"alexreardon/css-box-model","owner":"alexreardon","description":"Get accurate and well named css box model information about an Element 📦","archived":false,"fork":false,"pushed_at":"2023-01-03T21:41:26.000Z","size":1345,"stargazers_count":167,"open_issues_count":15,"forks_count":7,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-11T12:07:10.806Z","etag":null,"topics":["box","box-model","dom"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alexreardon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-04-16T00:40:18.000Z","updated_at":"2025-04-04T02:59:30.000Z","dependencies_parsed_at":"2023-02-01T10:15:16.624Z","dependency_job_id":null,"html_url":"https://github.com/alexreardon/css-box-model","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexreardon%2Fcss-box-model","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexreardon%2Fcss-box-model/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexreardon%2Fcss-box-model/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexreardon%2Fcss-box-model/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alexreardon","download_url":"https://codeload.github.com/alexreardon/css-box-model/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254535827,"owners_count":22087399,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["box","box-model","dom"],"created_at":"2024-07-31T05:01:08.205Z","updated_at":"2025-05-16T13:05:34.180Z","avatar_url":"https://github.com/alexreardon.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# `css-box-model` 📦\n\nGet accurate and well named [CSS Box Model](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Box_Model/Introduction_to_the_CSS_box_model) information about a [`Element`](https://developer.mozilla.org/en-US/docs/Web/API/Element).\n\n[![Build Status](https://travis-ci.org/alexreardon/css-box-model.svg?branch=master)](https://travis-ci.org/alexreardon/css-box-model)\n[![npm](https://img.shields.io/npm/v/css-box-model.svg)](https://www.npmjs.com/package/css-box-model)\n[![dependencies](https://david-dm.org/alexreardon/css-box-model.svg)](https://david-dm.org/alexreardon/css-box-model)\n[![Downloads per month](https://img.shields.io/npm/dm/css-box-model.svg)](https://www.npmjs.com/package/css-box-model)\n[![min](https://img.shields.io/bundlephobia/min/css-box-model.svg)](https://www.npmjs.com/package/css-box-model)\n[![minzip](https://img.shields.io/bundlephobia/minzip/css-box-model.svg)](https://www.npmjs.com/package/css-box-model)\n\nAny time you are using [`Element.getBoundingClientRect()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect) you might want to consider using `css-box-model` instead to get more detailed box model information.\n\n## Usage\n\n```js\n// @flow\nimport { getBox } from 'css-box-model';\n\nconst el: HTMLElement = document.getElementById('foo');\nconst box: BoxModel = getBox(el);\n\n// profit\n```\n\n## Installation\n\n```bash\n## yarn\nyarn add css-box-model\n\n# npm\nnpm install css-box-model --save\n```\n\n## The [CSS Box Model](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Box_Model/Introduction_to_the_CSS_box_model)\n\n![the box model](https://user-images.githubusercontent.com/2182637/46847224-f8a23e80-ce2e-11e8-80d6-0ca62a1871a7.png)\n\n| Box type    | Composition                         |\n| ----------- | ----------------------------------- |\n| Margin box  | margin + border + padding + content |\n| Border box  | border + padding + content          |\n| Padding box | padding + content                   |\n| Content box | content                             |\n\nThis our returned `BoxModel`:\n\n```js\nexport type BoxModel = {|\n  // content + padding + border + margin\n  marginBox: Rect,\n  // content + padding + border\n  borderBox: Rect,\n  // content + padding\n  paddingBox: Rect,\n  // content\n  contentBox: Rect,\n  // for your own consumption\n  border: Spacing,\n  padding: Spacing,\n  margin: Spacing,\n|};\n\n// Supporting types\n\n// This is an extension of DOMRect and ClientRect\nexport type Rect = {|\n  // ClientRect\n  top: number,\n  right: number,\n  bottom: number,\n  left: number,\n  width: number,\n  height: number,\n  // DOMRect\n  x: number,\n  y: number,\n  // Rect\n  center: Position,\n|};\n\nexport type Position = {|\n  x: number,\n  y: number,\n|};\n\nexport type Spacing = {\n  top: number,\n  right: number,\n  bottom: number,\n  left: number,\n};\n```\n\n## API\n\n### `getBox`\n\n\u003e (el: HTMLElement) =\u003e BoxModel\n\nUse `getBox` to return the box model for an element\n\n### `withScroll`\n\n\u003e `(original: BoxModel, scroll?: Position = getWindowScroll()) =\u003e BoxModel`\n\nThis is useful if you want to know the box model for an element relative to a page\n\n```js\nconst el: HTMLElement = document.getElementById('app');\nconst box: BoxModel = getBox(el);\nconst withScroll: BoxModel = withScroll(box);\n```\n\nYou are welcome to pass in your own `scroll`. By default we we use the window scroll:\n\n```js\nconst getWindowScroll = (): Position =\u003e ({\n  x: window.pageXOffset,\n  y: window.pageYOffset,\n});\n```\n\n### `calculateBox`\n\n\u003e `(borderBox: AnyRectType, styles: CSSStyleDeclaration) =\u003e BoxModel`\n\nThis will do the box model calculations without needing to read from the DOM. This is useful if you have already got a `ClientRect` / `DOMRect` and a `CSSStyleDeclaration` as then we can skip computing these values.\n\n```js\nconst el: HTMLElement = document.getElementById('app');\nconst borderBox: ClientRect = el.getBoundingClientRect();\nconst styles: CSSStyleDeclaration = window.getComputedStyles(el);\n\nconst box: BoxModel = calculateBox(borderBox, styles);\n```\n\n**`AnyRectType`** allows for simple interoperability with any rect type\n\n```js\ntype AnyRectType = ClientRect | DOMRect | Rect | Spacing;\n```\n\n### `createBox`\n\n\u003e `({ borderBox, margin, border, padding }: CreateBoxArgs) =\u003e BoxModel`\n\nAllows you to create a `BoxModel` by passing in a `Rect` like shape (`AnyRectType`) and optionally your own `margin`, `border` and or `padding`.\n\n```js\ntype CreateBoxArgs = {|\n  borderBox: AnyRectType,\n  margin?: Spacing,\n  border?: Spacing,\n  padding?: Spacing,\n|};\n```\n\n```js\nconst borderBox: Spacing = {\n  top: 10,\n  right: 100,\n  left: 20,\n  bottom: 80,\n};\nconst padding: Spacing = {\n  top: 10,\n  right: 20,\n  left: 20,\n  bottom: 10,\n};\n\nconst box: BoxModel = createBox({ borderBox, padding });\n```\n\n## Utility API\n\n\u003e Functions to help you interact with the objects we provide\n\n### `getRect`\n\n\u003e `(spacing: AnyRectType) =\u003e Rect`\n\nGiven any `Rect` like shape, return a `Rect`. Accepts any object that has `top`, `right`, `bottom` and `right` (eg `ClientRect`, `DOMRect`);\n\n```js\nconst spacing: Spacing = {\n  top: 0,\n  right: 100,\n  bottom: 50,\n  left: 50,\n};\n\nconst rect: Rect = getRect(spacing);\n\nconsole.log(rect);\n\n/*\n{\n  top: 0,\n  right: 100,\n  bottom: 50,\n  left: 50,\n  width: 100,\n  height: 50,\n  x: 0,\n  y: 0,\n  center: { x: 50, y: 50 },\n}\n*/\n```\n\n### `expand`\n\nUsed to expand a `Spacing`\n\n```js\n(target: Spacing, expandBy: Spacing) =\u003e Spacing;\n```\n\n```js\nconst original: Spacing = {\n  top: 10,\n  left: 11,\n  right: 21,\n  bottom: 22,\n};\n\nconst expandBy: Spacing = {\n  top: 1,\n  left: 2,\n  right: 3,\n  bottom: 4,\n};\n\nconst expanded: Spacing = expand(original, expandBy);\n\nconsole.log(expanded);\n\n/*\n{\n  // pulled back\n  top: 8,\n  left: 8\n  // pushed forward\n  bottom: 22,\n  right: 22,\n}\n*/\n```\n\n### `shrink`\n\nUsed to shrink a `Spacing`\n\n```js\n(target: Spacing, shrinkBy: Spacing) =\u003e Spacing;\n```\n\n```js\nconst original: Spacing = {\n  top: 10,\n  left: 10,\n  right: 20,\n  bottom: 20,\n};\n\nconst shrinkBy: Spacing = {\n  top: 2,\n  left: 2,\n  right: 2,\n  bottom: 2,\n};\n\nconst smaller: Spacing = shrink(original, shrinkBy);\n\nconsole.log(smaller);\n\n/*\n{\n  // pushed forward\n  top: 12,\n  left: 12\n  // pulled back\n  bottom: 18,\n  right: 18,\n}\n*/\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexreardon%2Fcss-box-model","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexreardon%2Fcss-box-model","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexreardon%2Fcss-box-model/lists"}