Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Document how to use scrollTop() properly #417

Open
jzaefferer opened this Issue · 18 comments

8 participants

@jzaefferer
Owner

Via discussion in #14515.

This should be added to scrollTop():

Note that scrollTop can be used to read, but not write, the document scroll position. To scroll the document, animated or not, you have to call `scrollTop()` on the body element:

<pre><code>
// Without animation
$( document.body ).scrollTop( 500 );

// With animation
$( document.body ).animate({
  scrollTop: 500
});
</code></pre>

Any examples elsewhere that suggest $( "html, body" ).animate({ scrollTop: ... }); are wrong, since this will cause the animation callback to get triggered twice.
@leobalter leobalter referenced this issue from a commit in leobalter/api.jquery.com
@leobalter leobalter .scrollTop(): document proper use of scrollTop on document body
Fixes #417
95bfc52
@jzaefferer
Owner

I just reopened the Core ticket, see there for details: http://bugs.jquery.com/ticket/14515#comment:8

@gnarf
Owner

I left some comments in #425 about the message here, I think we need to re-word it a bit and also add a similar note to scrollLeft()

@kswedberg
Collaborator

@jzaefferer I left a comment on the Core ticket for you.

@jzaefferer
Owner

Since Core won't try to normalize this, all we can do is document the canonical solution. Afaik this snippet works consistently and produces a single callback:

$( "html, body" ).animate({
  // scroll to end of page
  scrollTop: $(document).height()
}, 800).promise().then(function() {
  console.log("runs once!")
});

@leobalter would you update your branch and create a new PR? Thanks.

@gnarf
Owner

That snippet has other side effects...

Namely:

$( "html, body" ).animate({
  // scroll to end of page
  scrollTop: $(document).height()
}, 800).promise().then(function() {
  console.log("runs once!")
}).animate({
  scrollTop: 0
}, 800); // but only after this animation ALSO finishes

$("body").animate({opacity: 0}, 500); // oh this one too

The promise on a jQuery object only gets called when its default animation queue empties, not as an inline callback to animation completion.

@jaubourg
Collaborator

As gnarf said, you probably want something akin to this:

$.Deferred(function( defer ) {
    $( "html, body" ).animate({
        // scroll to end of page
        scrollTop: $(document).height()
    }, 800, defer.resolve );
}).done(function() {
    console.log( "runs once!" )
});
@gnarf gnarf closed this
@gnarf gnarf reopened this
@leobalter

IMHO, some of these examples are looking way complex to be presented as examples.

I think we can use the suggestions made by @gnarf to mention scrollLeft and we can also add another example using $.Deferred as mentioned by @jaubourg.

It might be worth to mention that jQuery Core don't try to force a normalization on this and explain why it's needed to handle scrollTop both on html and body to get a crossbrowser solution.

@jzaefferer
Owner

We can start with an example that doesn't have the callback, to keep things simple at first. Use that to talk about the underlying issue and lack of normalization. Then talk about the issue with animation callbacks and how to deal with that, along with another example.

@dmethvin
Owner

Can this be an article on learn perhaps, with a link from the api docs? It's starting to sound pretty big.

@kswedberg
Collaborator

:+1: to linking to a learn article.

@leobalter

I'll try to write something by the weekend.

challenge

Anyway, I don't want to prevent anyone else to write it as well. If we have other article to be posted on learn I can push mine to a blog, maybe.

@arthurvr
Collaborator

I'll try to write something by the weekend.

@leobalter Still interested in taking this? Or did you already do?

@leobalter
@jzaefferer
Owner

@arthurvr interested in taking this over? Or finding someone to write the docs? Sad to see this still open more than a year later...

@arthurvr
Collaborator

interested in taking this over? Or finding someone to write the docs? Sad to see this still open more than a year later...

That's true for basically ever ticket open here :( One day I'll get to it for sure, but time just limits me.

@arthurvr
Collaborator

@jzaefferer Although I do definitely agree that many things in this repo are taking way too long. There are still APIs from back in 2012 undocumented, just because we lack the time and the resources.

@dmethvin
Owner

@arthurvr the important thing is that we are making progress, thanks to you! This issue in particular seemed to get lots of people suggesting changes without a clear consensus on what to do. I think that's why it sat around so long, it is tedious to sort through these kinds of tickets and there is always concern you'll upset someone by ignoring their concerns. So go for the low-hanging fruit if it's easier.

@jzaefferer
Owner

Here's a good explanation of the underlying mess, along with a future-proof solution called document.scrollingElement: https://dev.opera.com/articles/fixing-the-scrolltop-bug/

If I read that correctly, we should document how to animate document.scrollingElement, along with a recommendation to load the polyfill.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.