CSS Coordinate Systems & Dimensioning

Posted Tuesday, March 15, 2022 by Sri.Tagged MEMO
EDIT STATUS:first draft

Window Viewport Concepts

In general computer graphics, a viewport is a rectangular device specific 'viewing region'. For a modeled world, the world coordinates can be used to define an area of interest that are then projected into the viewport. For 2D display on 2D devices this is merely tranforms, but for 3D on 2D this uses a projection matrix and a virtual camera coordinate.

In HTML5 on the desktop, the viewport is the part of the browser window that has the document you want to view. This is the 'layout viewport' of the window, which is the part without browser chrome.

The top-level window aso has a "visual viewport" which defines what part of the layout viewport to display, In effect, this is used to implement "magnifying", but doesn't support "zooming out" past 100% of the layout view.

Base Computer Graphic Concepts

Coordinate Systems

In computer graphics, visual objects are modeled mathematically using a "coordinate system" to describe where objects are. Coordinate systems have "units" (pixels, inches, meters) along a set of "coordinate axes" (x, y, etc) to place elements into the "coordinate space". The center of this space is called the "origin" where each axis is zero.

A computer graphics coordinate system always has to have the following defined:

  • the default location of the origin
  • the direction of positive coordinate values relative to the origin
  • the rotation direction of angles

This is sometimes called the "handedness" of a coordinate system. 3D Computer graphics systems tend to use the "right handed" coordinate systems:

  • origin is center of the modeling space, angle origin is on positive x-axis
  • with positive x on the "right" axis and positive y on the "up" axis
  • positive z is usually "farther" (lower numbers draw before higher numbers)
  • positive angles are counterclockwise starting from the x axis as 0 degrees

CSS flips z-order with z-index (lower numbers draw after higher)

Traditional 2D computer graphics systems tend to use its own convention:

  • origin is at the top-left of the screen, angle origin is on negative Y axis
  • positive-x goes to the right, positive-y goes DOWN from the origin
  • positive-z goes goes AWAY from you, usually
  • positive angle start at 0 at the top and go CLOCKWISE

World Definition

Creating a "world" inhabited by of visual objects consists of giving each of them its own coordinates in the world's "coordinate space". However, there are many coordinate spaces in a computer graphics application!

  • On the Modeling side, your visual objects may have their own "local coordinates", with the origin for each object in the center or at its point of rotation.

  • On the Device side, your screen has its own coordinates system that differs from your world.

There are many "transformations" that occur between coordinate system data. For example, a 3D game on a web browser might have:


  • elements designed using their local coordinate system...
  • mapped to a place in the world coordinate system...


  • mapped to a view that limits how much as being seen of the world...
  • mapped from 3D to 2D coordinates using "2d projection"
  • mapped to viewport that is all the "visible 2D data"...


  • mapped to web page with its own page coordinates...
  • mapped to a browser window with its own scrollable area...
  • mapped to a brower's "zoom factor"...


  • mapped to the browser host device's screen coordinates

CSS Specifics

Coordinate Systems of the Browser


The CSS Coordinate System has the origin (0,0) at the top left, with the 0 angle pointing up and positive angles rotating clockwise.

For web browsers, the basic coordinate system references are defined by the window and the document that is shown inside the window. The elements inside the document also have their own coordinate systems.

There seem to be these coordinate system contexts used consistently in the documentation:


The origin is top-left of containing VIEWPORT, which is the part of the browser that shows the document.


The origin is top left of Document, and coordinates of the elements in the page are relative to it. This is displayed inside the Client area.


The origin is top-left of the display screen. The Client area is some subset of displayed somewhere on the screen in a window.

A Page has a root Element in document.documentElement, which has the same coordinate system conventions as other elements (see next section):


The origin is top-left corner of the Element. The origin is inset by the node's padding-left and padding-top, so 0,0 may not be where you expect.

CSS uses 2D coordinate system conventions:

  • increasing x values go to the right
  • increasing y values go down
  • angles are clockwise, with the angle origin at the top
  • the z-index value stacks positive values before negative values

Element Properties and Dimensions

Every element in an HTML document has a 'margin', 'border', and 'padding' that affects the size of a given box. These properties are always inspectable:


the size of the entire element, not including margin.




the size of the content area inside the element.



Because elements can contain child elements as scrollable content with hidden overflow, these properties can help us compute offsets:


the size of the element's child contents, even if overflow is hidden.



The meaning of these terms are also explained here. The Page Coordinates correspond to

These will return fractional values, which can happen if they have a CSS transform applied.

You can ALSO use Javascript's getBoundingClientRect() to return a DOMRect data structure of the "rendered size" on the page in the Client Coordinates context:

x, y

the origin, "typically the top-left corner"

width, height

the size

top, left

the origin, "typically the top-left corner"


if width less-than 0, returns x


if height greater-than 0, returns y

Event Coordinate Systems

Events always report where they happened within their event target:

offsetX, offsetY

coordinates inside the event target

clientX, clientY

coordinates relative to browser viewport origin

pageX, pageY

coordinates relative to the document origin

screenX, screenY

coordinates relative to the screen origin

As mentioned before, calling Element.getBoundingClientRect() returns the client-relative coordinates, so this can be used as-is with the clientX, clientY information in the event.

But what if you need the coordinates relative to another element? Just use getBoundingClientRect() on both elements, and do some arithmetic.

Pinch to Zoom Display Scaling

Every browser window object (and iframes) has the main "Layout Viewport" that we've discussed above, but there is a second property for the root viewport called visualViewport used to implement things like "pinch to zoom/pan". It specifies a subarea of the Layout Viewport to magnify/pan.

offsetLeft, offsetTop

where within the layoutViewport

height, width

size of the visualViewport

pageLeft, pageTop

offset from starting visualViewport


pinch-zoom factor

Operating System Display Properties

You can also access the dimensions of the screen through the window.screen object:

width, height

dimensions of the screen


available width usable by browser window


available height minus operating system stuff like taskbar


display color palette (24bit = 16.7million colors)


bits per pixel (256 colors = 8, 16.7 million colors = 24)


{ type, angle }

Obsolete Methods?

When searching for information about browser element dimensions, you get a lot of old stuff relating to jQuery methods like:

  • innerWidth, innerHeight
  • outerWidth, outerHeight

These also exist as window properties, maybe for compatibility, maybe because these are operating system window properties and not browser window properties?

Other Element Typed?

The SVG and Canvas types may have their own conventions, and I'm not sure different they are compared to CSS. Additional, there is the WebGL display context with its own conventions too.

HTML can contain SVGElements, Canvas elements, and WebGL elements inside of Canvas elements. Hopefuly they all use similar conventions.