Coordinate systems

In the coordinate systems used by web technologies, convention dictates that the horizontal offset is called the x-coordinate, where a negative value indicates a position to the left of the origin and a positive value is to the right of the origin. The y-coordinate specifies the vertical offset, with a negative value being above the origin and a positive value being below the origin.

On the web, the default origin is the top-left corner of a given context (with positive y-coordinate values being below the origin). Note that this is unlike most mathematical models, where the origin is at the bottom-left corner, with positive y-coordinate values being above the origin.

When using the third dimension to layer objects from front to back, we use the z-axis. The z-axis runs from the viewer to the screen's surface. The CSS z-index attribute affects where positioned elements sit on this axis, giving the effect of moving away from or toward the viewer.

There are four standard coordinate systems used by the CSS object model. To help visualize the main systems, the following diagram shows a monitor with a browser window that contains content scrolled outside of the viewport. Page content that is scrolled outside of the viewport is shown as semi-transparent above the browser window to indicate where the origin for "page" coordinates would be. The origin of the "client", "page", and "viewport" coordinates systems are highlighted.

Coordinates specified using the "offset" model use the top-left corner of the element being examined, or on which an event has occurred.

For example, when a mouse event occurs, the position of the mouse as specified in the event's offsetX and offsetY properties are given relative to the top-left corner of the node to which the event has been delivered. The origin is inset by padding-edge which is the edge between the padding area and the border area.

The "viewport" (or "client") coordinate system uses as its origin the top-left corner of the viewport or browsing context in which the event occurred. This is the entire viewing area in which the document is presented.

On a desktop computer, for example, the MouseEvent.clientX and MouseEvent.clientY properties indicate the position of the mouse cursor at the moment the event occurred, relative to the top-left corner of the window. When using a stylus or a pointer, the Touch.clientX and Touch.clientY coordinates in a touch event are relative to the same origin.

The top-left corner of the window is always (0, 0), regardless of the content of the document or any scrolling that may have been done. In other words, scrolling the document will change the viewport coordinates of a given position within the document.

The "page" coordinate system gives the position of a pixel relative to the top-left corner of the entire rendered Document. That means that a point in an element within the document will have the same coordinates after the user scrolls horizontally or vertically in the document unless the element moves via layout changes.

Mouse events' pageX and pageY properties provide the position of the mouse at the time the event was generated, given relative to the top-left corner of the document. Touch.pageX and Touch.pageY coordinates in a touch event are relative to the same origin.

Finally, we come to the "screen" model where the origin is the top-left corner of the user's screen space. Each point in this coordinate system represents a single logical pixel, and so values increment and decrement by integer values along each axis. The position of a given point within a document will change if the containing window is moved, for example, or if the user's screen geometry changes (by changing display resolution or by adding or removing monitors to their system).

The MouseEvent.screenX and MouseEvent.screenY properties give the coordinates of a mouse event's position relative to the screen's origin. Touch.screenX and Touch.screenY coordinates in a touch event are relative to the same origin.

Let's take a look at an example that logs mouse coordinates in an element. Whenever the mouse enters, moves around inside, or exits the inner box, the events are handled by logging the current mouse coordinates in each of the four available systems.

For the JavaScript, the code sets up the event handlers on the inner box by calling addEventListener() for each of the types mouseenter, mousemove, and mouseleave. For each of the events, we're calling the setCoords() function which sets the inner text of the <p> element with the coordinates for each system.

const log = document.querySelector(".log");
const inner = document.querySelector(".inner");

function setCoords(e) {
  log.innerText = `
    Offset X/Y: ${e.offsetX}, ${e.offsetY}
    Viewport X/Y: ${e.clientX}, ${e.clientY}
    Page X/Y: ${e.pageX}, ${e.pageY}
    Screen X/Y: ${e.screenX}, ${e.screenY}`;
}

inner.addEventListener("mousemove", setCoords);
inner.addEventListener("mouseenter", setCoords);
inner.addEventListener("mouseleave", setCoords);

The HTML contains a <p> with the "log" class, which displays the data from the mouse events.

<div class="outer">
  <div class="inner">
    <p class="log">Mouse over this section to view coordinates</p>
  </div>
</div>

The class "outer" for the containing box is intentionally too wide to view the effects of mouse coordinates when the content is scrolled. The "inner" paragraph is where mouse events are tracked and logged.

.outer {
  width: 1000px;
}

.inner {
  font-family: monospace;
  position: relative;
  width: 500px;
  height: 150px;
  top: 25px;
  left: 100px;
  background-color: darkblue;
  color: white;
  cursor: crosshair;
  user-select: none;
}

.log {
  position: relative;
  width: 100%;
  text-align: center;
}

Here you can see the results in action. As you mouse in and around the blue box, watch the values of the mouse's X and Y coordinates change in the various coordinate systems.

• Using CSS transforms: how to alter a coordinate system
• Coordinates of a MouseEvent:
  • MouseEvent.offsetX and MouseEvent.offsetY
  • MouseEvent.clientX and MouseEvent.clientY
  • MouseEvent.pageX and MouseEvent.pageY
  • MouseEvent.screenX and MouseEvent.screenY
• Coordinates of a Touch:
  • Touch.clientX and Touch.clientY
  • Touch.pageX and Touch.pageY
  • Touch.screenX and Touch.screenY