‚̧Namely, Pickled Meatballs

    css-box-model
    TypeScript icon, indicating that this package has built-in type declarations

    1.2.1¬†‚Äʬ†Public¬†‚Äʬ†Published

    css-box-model ūüď¶

    Get accurate and well named CSS Box Model information about a Element.

    Build Status npm dependencies Downloads per month min minzip

    Any time you are using Element.getBoundingClientRect() you might want to consider using css-box-model instead to get more detailed box model information.

    Usage

    // @flow
    import { getBox } from 'css-box-model';
     
    const el: HTMLElement = document.getElementById('foo');
    const box: BoxModel = getBox(el);
     
    // profit

    Installation

    ## yarn 
    yarn add css-box-model
     
    # npm 
    npm install css-box-model --save

    The CSS Box Model

    the box model

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

    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 / DOMRect and a CSSStyleDeclaration as then we can skip computing these values.

    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 (AnyRectType) 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 });

    Utility API

    Functions to help you interact with the objects we provide

    getRect

    (spacing: AnyRectType) => Rect

    Given any Rect like shape, return a Rect. Accepts any object that has top, right, bottom and right (eg ClientRect, DOMRect);

    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 },
    }
    */

    expand

    Used to expand a Spacing

    (target: Spacing, expandBy: Spacing) => Spacing;
    const original: Spacing = {
      top: 10,
      left: 11,
      right: 21,
      bottom: 22,
    };
     
    const expandBy: Spacing = {
      top: 1,
      left: 2,
      right: 3,
      bottom: 4,
    };
     
    const expanded: Spacing = expand(original, expandBy);
     
    console.log(expanded);
     
    /*
    {
      // pulled back
      top: 8,
      left: 8
      // pushed forward
      bottom: 22,
      right: 22,
    }
    */

    shrink

    Used to shrink a Spacing

    (target: Spacing, shrinkBy: Spacing) => Spacing;
    const original: Spacing = {
      top: 10,
      left: 10,
      right: 20,
      bottom: 20,
    };
     
    const shrinkBy: Spacing = {
      top: 2,
      left: 2,
      right: 2,
      bottom: 2,
    };
     
    const smaller: Spacing = shrink(original, shrinkBy);
     
    console.log(smaller);
     
    /*
    {
      // pushed forward
      top: 12,
      left: 12
      // pulled back
      bottom: 18,
      right: 18,
    }
    */

    Install

    npm i css-box-model

    DownloadsWeekly Downloads

    1,181,426

    Version

    1.2.1

    License

    MIT

    Unpacked Size

    31.6 kB

    Total Files

    10

    Last publish

    Collaborators

    • alexreardon