jQuery Mouse Events: PageX/Y vs. ClientX/Y
Posted March 8, 2010 at 9:19 AM
When I first starting playing with jQuery events, a lot of what I learned about the jQuery Event object was through trial and error. While I could be remembering incorrectly, I used to find that the jQuery documentation was good at describing the event handlers, but not so good at describing the event object; as such, while I knew that the jQuery event object was a standardized event object, I was never 100% sure which parts of it I was supposed to be using.
| | | | | |
| | | |||
| | | |
Through my trial and error, I started to use the clientX and clientY mouse coordinates in the jQuery event object. These coordinates gave me the X and Y offset of the mouse relative to the top-left corner of the browser's view port. As I was reading the jQuery 1.4 Reference Guide by Karl Swedberg and Jonathan Chaffer, however, I saw that they often referred to the pageX and pageY coordinates. After checking the updated jQuery documentation, I saw that these were the coordinates standardized by jQuery; and, I saw that they gave me the X and Y offset of the mouse relative to the entire document (not just the view port).
To see the difference between these two coordinate systems, I set up a page that would log mouse click events against a visible coordinate grid.
- <!DOCTYPE HTML>
- <html>
- <head>
- <title>jQuery Mouse Events: ClientX vs. PageX</title>
- <style type="text/css">
-
- div.grid {
- border: 1px solid #CCCCCC ;
- cursor: pointer ;
- font: 10px verdana ;
- height: 99px ;
- position: absolute ;
- width: 99px ;
- z-index: 100 ;
- }
-
- </style>
- <script type="text/javascript" src="jquery-1.4.2.js"></script>
- <script type="text/javascript">
-
- // I draw the grid on the document.
- function createGrid(){
- var body = $( "body" );
-
- // Draw the X axis.
- for (var x = 0 ; x <= 2000 ; x += 100){
-
- // Draw the Y axis.
- for (var y = 0 ; y <= 2000 ; y += 100){
-
- $( "<div class='grid'></div>" )
- .appendTo( body )
- .css({
- left: (x + "px"),
- top: (y + "px")
- })
- .text( x + "," + y )
- ;
-
- }
-
- }
- };
-
-
- // When the DOM is ready, initialize the scripts.
- jQuery(function( $ ){
-
- // Create the grid for coordinate affordance.
- createGrid();
-
- // Bind the mouse event to the document so that we
- // can see what kind of coordinates we have to play
- // with.
- $( document ).click(
- function( event ){
-
- // Client variables.
- console.log(
- "clientX/Y: " +
- event.clientX + ", " +
- event.clientY
- );
-
- // Page variables. NOTE: These are the ones
- // that are officially supported by the
- // jQuery Event object.
- console.log(
- "pageX/Y: " +
- event.pageX + ", " +
- event.pageY
- );
-
- // Hrule.
- console.log( "......" );
-
- }
- );
-
- });
-
- </script>
- </head>
- <body>
- <!-- Nothing needed here. -->
- </body>
- </html>
As you can see, I create a 2000 x 2000 pixel grid that will give me both horizontal and vertical scrolling. And, when I scroll both right and down, and then click on the document, I get the following console output:
| | | | | |
| |  | | ||
| | | |
As you can see, the clientX and clientY coordinates give me the mouse position relative to the view port, regardless of the scroll of the document. The pageX and pageY coordinates, on the other hand, give me the mouse position relative to the top, left of the entire document, again regardless of the scrolling.
Which mouse event coordinates you should be using is not really a question for debate - the pageX and pageY coordinates are the ones that have been standardized by jQuery. In order to keep your code as cross-browser compatible as possible, you should rely on pageX and pageY. It is unfortunate that I did not know about this until just recently - I am quite sure that I have posted a lot of code that accidentally relied on the proprietary event properties, clientX and clientY.
Reader Comments
Thanks a lot for this post! Good that you took notice of it : this will be helpful for my map browser.
@Philippe,
The standardization of the jQuery event object is nice... especially when you finally know what the standard actually is ;)
I've been trying to find a way to determine the X/Y mouse coordinates in relation to a given element. That way I could tell if my mouse is the left 50% of a given <div>, or the top 33% of a given image and show/hide things appropriately.
Is there a way to extrapolate the pageX/Y into coords related to a certain element.
@Scott,
For something like that, I would use the offset() of the given element in conjunction with the pageX/pageY.
I use this approach a lot, but have not pointed it out specifically. I'll write up a quick post and paste a link here.
@Scott,
Take a look at this exploration:
http://www.bennadel.com/blog/1871-Translating-Global-jQuery-Event-Coordinates-To-A-Local-Context.htm
Very good article. Opened up my mind to many cool possibilities.
Thanks, I want to try this on the map.
@Peter,
Glad you like it. Drop another comment if you come up with some cool ways to use this.
thanks a lot,
Very useful. I've been using pageX/pageY as this is what I learnt initially, so I guess thats a bonus!
On the other hand, I do see some benefits of having both values, as it can often be useful to know *where* in the page the visitors browser is viewing. I wouldn't necessarily ignore clientX/clientY usage because, for the right task, namely some fancy jQuery-based animation, this is exactly what is needed.
Am I wrong to suggest this?
I think advanced jQuery visuals on sites would probably rely on a mixture of client/page/X/Y along with offset() and many other jQuery blessings.
@Rhys,
I think both sets of values definitely have their place. The big question is - can you rely on the clientX/clientY to always be there? The beauty of the jQuery library is that it standardizes what is available in the event object; according to the docs, they promise to supply the pageX/pageY, not the clientX/clientY. So, while I have used it without problem, I am not sure that means that it will always hold the values you expect.
The Compatibility information listed at http://www.quirksmode.org/dom/w3c_cssom.html
infact shows clientX,clientY to be the one consistent on most browsers. So it should be safe using clientX,clientY right ?
@Jitendra,
I am not sure how to best answer that. Even if it is most consistent, we are using a library that standardizes on a given set of properties. I think , if we use the library (jQuery), then we need to depend more on what they standardize on. But, as I said in the blog post, I was using the wrong ones for a while without any problem... so it appears to be quite safe by coincidence.
