Definable distance pagination for ScrollView

[rxb]

This is an enhancement for ScrollView that adds the ability to paginate based on a width other than the width of the ScrollView itself. This is a fairly common pattern used on apps like Facebook, App Store, and Twitter to scroll through a horizontal set of cards or icons:

After trying to accomplish this only with JS, it appears that attempting to take over an in-progress native scroll animation with JS is always going to result in some amount of jankiness and jumping.

This pull request uses scrollViewWillEndDragging in RCTScrollView.m to adjust targetContentOffset based on two new optional props added to ScrollView. snapToInterval sets the multiple that the ScrollView will come to rest on. snapToAlignment sets the relative alignment of the snap start, center, or end.

Here's an example of it in action:
https://vid.me/aoby

Here is some sample code to try it out yourself:

var SnapTest = React.createClass({

  render: function() {
    var blocks = [];
    for(var i=0; i<=30; i++){
      blocks.push("i");
    }
    var blockW = 100;
    return (
      <ScrollView 
        horizontal={true} 
        decelerationRate={0}
        snapToInterval={blockW}
        snapToAlignment="start"
        >
        {blocks.map(function(m,i){
          return (
            <View key={i} style={{width: blockW, height: blockW, padding:16, backgroundColor: (i%2==0)?'cornflowerblue':'royalblue', borderWidth: 1, borderColor: "#fff"}}>
              <Text style={{color: 'white', fontWeight: '800'}}>{i}</Text>
            </View>
          );
        })}
      </ScrollView>
    );
  }
});

Would love to get your thoughts on this direction!

cc: @brentvatne #1362

[brentvatne]

This looks great, I'll read over more carefully and try it out tonight 😄 edit: scratch that, went on massive run today and am totally exhausted, tomorrow 👍

[brentvatne]

This comment can go

[rxb]

fixed

[brentvatne]

@rxb - could you also squash these commits into one?

[brentvatne]

Not sure who owns ScrollView cc @tadeuzagallo @nicklockwood

[rxb]

@brentvatne Thanks for the notes. Everything except for the isHorizontal question is fixed and squashed into 1 commit.

[rxb]

What do you think about tweaking the api to match up with the CSS scroll-snap-points spec?
http://www.w3.org/TR/css-snappoints-1/#scroll-snap-type

Looks like it will be in most browsers soon:
http://caniuse.com/#feat=css-snappoints
https://www.chromestatus.com/features/5721832506261504

[brentvatne]

@rxb - Absolutely! I think the closer that we can be to the w3 spec the better. Great point, can you adjust accordingly? cc @vjeux

[vjeux]

Have you tried paginate={true} on ScrollView, doesn't it solve your use case?

[brentvatne]

@vjeux - there are several problems with paginate={true}:

• Fixed page size to the viewport width
  • If it were to support variable widths, it would need to have an option to specify where to snap to (middle, left-side, right-side)
• Horizontal paging only

Like in the screenshots that @rxb posted in the original comment above, it's quite common to want to snap to something other than the viewport width

[ide]

You can support variable widths with pagination with a couple of tricks -- that is how the Apple Photos app works.

The core difference between pagination and scroll snapping is that pagination snaps to the next page even if you swipe hard, while scroll snapping accounts for momentum so you could end up several pages away.

[rxb]

I think where that difference matters most is when you are scrolling through items that are not close to the screen width, like photos on FB profiles:
https://vid.me/V4Bz

It would be rough if it forced one-at-a-time, but free scrolling would feel like driving on a greased track.

[sahrens]

@nicklockwood: what do you think of this?

[rxb]

@brentvatne Awesome, I'll sync things up with the W3C spec.

After testing this in a more realistic screen -- where the horizontal scrolling section is one part of a longer vertical scrollview -- ran into that nested scrolling bug from: #41 .

[vjeux]

Just wanted to said that I patched this to prototype a use case that we wanted to do internally and it works really well :)

Sorry it takes so long to review :(

[paramaggarwal]

merge conflict artifact?

[rxb]

Thanks for the catch, fixed.

[rxb]

@vjeux Happy to hear it worked for you.

I keep meaning to get back to this and tweak to match the W3C scroll snap points spec. Would love to get anyone's thoughts on this interface:

Enable snapping
http://www.w3.org/TR/css-snappoints-1/#scroll-snap-type
prop: scrollSnapType
values: none proximity (mandatory could be supported in the future )

Set snapping interval
http://www.w3.org/TR/css-snappoints-1/#propdef-scroll-snap-points-x
prop: scrollSnapPoints (W3C spec defines scroll-snap-points-x and scroll-snap-points-y independently, but it seems that RN encourages scrolling in one direction at a time)
values: none repeat([interval in pixels]) (The repeat seems unnecessary, but it is part of the spec.)

Set alignment of snap relative to scroll container
http://www.w3.org/TR/css-snappoints-1/#propdef-scroll-snap-destination
prop: scrollSnapDestination
values: [offset in pixels] (Spec defines values for x and y offsets together, but this seems unnecessary if RN ScrollViews are only scrolling in one direction. Setting this explicitly in pixels gives more flexibility, but is more work than start, center, end )

[sahrens]

ping @nicklockwood

[chirag04]

+1

Just stumbled upon this while looking to detect page changes on a horizontal listview. This could be useful i guess.

[chirag04]

@vjeux Does it make sense to emulate css api if it is not part of style?

My 2cents: I liked the initial api suggested by @rxb.

[vjeux]

The guideline is to first try to design the best API based on what exists on iOS, Android, web... Then once we found one, if it is close enough to the web one, it's preferable to use it. If the web one doesn't make sense, we shouldn't tie ourself to it

[chirag04]

any thoughts one this one?

cc @nicklockwood

[chirag04]

@vjeux Mind sharing the patch? Wondering if anyone is having any opinions on this. Happy to implement thoughts that others may have.

[syrusakbary]

Would love having this patch merged into react native!
👍

[vjeux]

@facebook-github-bot shipit

[facebook-github-bot]

Thanks for importing. If you are an FB employee go to https://our.intern.facebook.com/intern/opensource/github/pull_request/437412899771084/int_phab to review.

[chirag04]

Awesome. Thanks 👍

Lrn flashcards will use this ;)

[vjeux]

"Failed to apply patch". @rxb would you be willing to rebase? Sorry for the wait

[rxb]

Should be back in business, rebased with master. The Travis e2e test is failing, but I can't tell if that's because of something in this PR or a general thing that's happening. Seems like almost all the recent PRs are failing that.

[vjeux]

Travis is broken because of our android push. Unlikely your fault

[vjeux]

@facebook-github-bot shipit

[facebook-github-bot]

Thanks for importing. If you are an FB employee go to https://our.intern.facebook.com/intern/opensource/github/pull_request/437412899771084/int_phab to review.

[rxb]

Thanks, everybody!

[vjeux]

Thanks for sticking with us and sorry it took that much time!

[aleclarson]

I'm surprised an onSnap prop wasn't included. Thoughts?

[erickreutz]

Any plans to bring this functionality to Android?

[me-abhinav]

+1 for Android

[me-abhinav]

I can create a pull request for Android if the owner wants.