jQuery Mouse Events: PageX/Y vs. ClientX/Y
Posted March 8, 2010 at 9:19 AM by Ben Nadel
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.
hi, thank you for the good article.
if I have <div style="height:600px;width:800px;overflow:auto;"> with 2 scollbars. How to determine mouse position. if I scroll down/right, the pageX/pageY show same numbers.
@rick,
after google search, scrollTop() is what I want. :-)
I've been a bit confused about this. Every bit of documentation I can find seems to say to use pageX/pageY. However, that always returns 0 for me in my jQuery on an iPhone. After some digging, I came across this page:
https://github.com/jquery/jquery-mobile/issues/734
which has some sample code with this comment in it:
// (in iOS event.pageX and event.pageY are always 0 )
which seems to back up my conclusion. I don't know if this is a failing of mobile safari or of jQuery, but it seems that pageX and pageY isn't usable on iOS.
Thank you Ben Nadal for providing us a useful knowledge, but I have some concerns about using the PageX,Y as a standard relative.
I mean that if I have to show something relative to viewport and also under the mouse hover (mouse position relative to view ports' x and y-axis), In that case how can I find the mouse position relative to viewport, if I use e.pageY then it will return me the coordinate related to the full browser?
Thanks,
Hussain
good one.....
