# SnapHelper

Artifact: [androidx.recyclerview:recyclerview](https://developer.android.com/jetpack/androidx/releases/recyclerview) [View Source](https://cs.android.com/search?q=file:androidx/recyclerview/widget/SnapHelper.java+class:androidx.recyclerview.widget.SnapHelper) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/recyclerview#1.0.0)

*** ** * ** ***


```
public abstract class SnapHelper extends RecyclerView.OnFlingListener
```

<br />

|---|---|---|
| [java.lang.Object](https://developer.android.com/reference/java/lang/Object.html) |||
| ↳ | [androidx.recyclerview.widget.RecyclerView.OnFlingListener](https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView.OnFlingListener) ||
|   | ↳ | [androidx.recyclerview.widget.SnapHelper](https://developer.android.com/reference/androidx/recyclerview/widget/SnapHelper) |

Known direct subclasses [LinearSnapHelper](https://developer.android.com/reference/androidx/recyclerview/widget/LinearSnapHelper), [PagerSnapHelper](https://developer.android.com/reference/androidx/recyclerview/widget/PagerSnapHelper)

|---|---|
| `https://developer.android.com/reference/androidx/recyclerview/widget/LinearSnapHelper` | Implementation of the `https://developer.android.com/reference/androidx/recyclerview/widget/SnapHelper` supporting snapping in either vertical or horizontal orientation. |
| `https://developer.android.com/reference/androidx/recyclerview/widget/PagerSnapHelper` | Implementation of the `https://developer.android.com/reference/androidx/recyclerview/widget/SnapHelper` supporting pager style snapping in either vertical or horizontal orientation. |

*** ** * ** ***

Class intended to support snapping for a `https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView`.

SnapHelper tries to handle fling as well but for this to work properly, the `https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView.LayoutManager` must implement the `https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView.SmoothScroller.ScrollVectorProvider` interface or you should override `https://developer.android.com/reference/androidx/recyclerview/widget/SnapHelper#onFling(int,int)` and handle fling manually.

## Summary

| ### Public constructors |
|---|
| `https://developer.android.com/reference/androidx/recyclerview/widget/SnapHelper#SnapHelper()()` |

| ### Public methods |
|---|---|
| `void` | `https://developer.android.com/reference/androidx/recyclerview/widget/SnapHelper#attachToRecyclerView(androidx.recyclerview.widget.RecyclerView)(@https://developer.android.com/reference/androidx/annotation/Nullable https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView recyclerView)` Attaches the `https://developer.android.com/reference/androidx/recyclerview/widget/SnapHelper` to the provided RecyclerView, by calling `https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView#setOnFlingListener(androidx.recyclerview.widget.RecyclerView.OnFlingListener)`. |
| `abstract @https://developer.android.com/reference/androidx/annotation/Nullable int[]` | `https://developer.android.com/reference/androidx/recyclerview/widget/SnapHelper#calculateDistanceToFinalSnap(androidx.recyclerview.widget.RecyclerView.LayoutManager,android.view.View)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView.LayoutManager layoutManager, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/view/View.html targetView )` Override this method to snap to a particular point within the target view or the container view on any axis. |
| `int[]` | `https://developer.android.com/reference/androidx/recyclerview/widget/SnapHelper#calculateScrollDistance(int,int)(int velocityX, int velocityY)` Calculated the estimated scroll distance in each direction given velocities on both axes. |
| `abstract @https://developer.android.com/reference/androidx/annotation/Nullable https://developer.android.com/reference/android/view/View.html` | `https://developer.android.com/reference/androidx/recyclerview/widget/SnapHelper#findSnapView(androidx.recyclerview.widget.RecyclerView.LayoutManager)(https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView.LayoutManager layoutManager)` Override this method to provide a particular target view for snapping. |
| `abstract int` | `https://developer.android.com/reference/androidx/recyclerview/widget/SnapHelper#findTargetSnapPosition(androidx.recyclerview.widget.RecyclerView.LayoutManager,int,int)( https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView.LayoutManager layoutManager, int velocityX, int velocityY )` Override to provide a particular adapter target position for snapping. |
| `boolean` | `https://developer.android.com/reference/androidx/recyclerview/widget/SnapHelper#onFling(int,int)(int velocityX, int velocityY)` Override this to handle a fling given the velocities in both x and y directions. |

| ### Protected methods |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/Nullable https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView.SmoothScroller` | `https://developer.android.com/reference/androidx/recyclerview/widget/SnapHelper#createScroller(androidx.recyclerview.widget.RecyclerView.LayoutManager)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView.LayoutManager layoutManager)` Creates a scroller to be used in the snapping implementation. |
| `@https://developer.android.com/reference/androidx/annotation/Nullable https://developer.android.com/reference/androidx/recyclerview/widget/LinearSmoothScroller` | `[createSnapScroller](https://developer.android.com/reference/androidx/recyclerview/widget/SnapHelper#createSnapScroller(androidx.recyclerview.widget.RecyclerView.LayoutManager))(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView.LayoutManager layoutManager)` **This method is deprecated.** use `https://developer.android.com/reference/androidx/recyclerview/widget/SnapHelper#createScroller(androidx.recyclerview.widget.RecyclerView.LayoutManager)` instead. <br /> |

## Public constructors

### SnapHelper

Added in 1.0.0

```
public SnapHelper()
```

## Public methods

### attachToRecyclerView

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/recyclerview#1.0.0)

```
public void attachToRecyclerView(@Nullable RecyclerView recyclerView)
```

Attaches the `https://developer.android.com/reference/androidx/recyclerview/widget/SnapHelper` to the provided RecyclerView, by calling `https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView#setOnFlingListener(androidx.recyclerview.widget.RecyclerView.OnFlingListener)`. You can call this method with `null` to detach it from the current RecyclerView.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/Nullable https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView recyclerView` | The RecyclerView instance to which you want to add this helper or `null` if you want to remove SnapHelper from the current RecyclerView. |

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` | if there is already a `https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView.OnFlingListener` attached to the provided `https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView`. |
| `https://developer.android.com/reference/java/lang/IllegalStateException.html` |   |

### calculateDistanceToFinalSnap

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/recyclerview#1.0.0)

```
public abstract @Nullable int[] calculateDistanceToFinalSnap(
    @NonNull RecyclerView.LayoutManager layoutManager,
    @NonNull View targetView
)
```

Override this method to snap to a particular point within the target view or the container view on any axis.

This method is called when the `https://developer.android.com/reference/androidx/recyclerview/widget/SnapHelper` has intercepted a fling and it needs to know the exact distance required to scroll by in order to snap to the target view.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView.LayoutManager layoutManager` | the `https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView.LayoutManager` associated with the attached `https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView` |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/view/View.html targetView` | the target view that is chosen as the view to snap |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/Nullable int[]` | the output coordinates the put the result into. out\[0\] is the distance on horizontal axis and out\[1\] is the distance on vertical axis. |

### calculateScrollDistance

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/recyclerview#1.0.0)

```
public int[] calculateScrollDistance(int velocityX, int velocityY)
```

Calculated the estimated scroll distance in each direction given velocities on both axes.

| Parameters |
|---|---|
| `int velocityX` | Fling velocity on the horizontal axis. |
| `int velocityY` | Fling velocity on the vertical axis. |

| Returns |
|---|---|
| `int[]` | array holding the calculated distances in x and y directions respectively. |

### findSnapView

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/recyclerview#1.0.0)

```
public abstract @Nullable View findSnapView(RecyclerView.LayoutManager layoutManager)
```

Override this method to provide a particular target view for snapping.

This method is called when the `https://developer.android.com/reference/androidx/recyclerview/widget/SnapHelper` is ready to start snapping and requires a target view to snap to. It will be explicitly called when the scroll state becomes idle after a scroll. It will also be called when the `https://developer.android.com/reference/androidx/recyclerview/widget/SnapHelper` is preparing to snap after a fling and requires a reference view from the current set of child views.

If this method returns `null`, SnapHelper will not snap to any view.

| Parameters |
|---|---|
| `https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView.LayoutManager layoutManager` | the `https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView.LayoutManager` associated with the attached `https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView` |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/Nullable https://developer.android.com/reference/android/view/View.html` | the target view to which to snap on fling or end of scroll |

### findTargetSnapPosition

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/recyclerview#1.0.0)

```
public abstract int findTargetSnapPosition(
    RecyclerView.LayoutManager layoutManager,
    int velocityX,
    int velocityY
)
```

Override to provide a particular adapter target position for snapping.

| Parameters |
|---|---|
| `https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView.LayoutManager layoutManager` | the `https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView.LayoutManager` associated with the attached `https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView` |
| `int velocityX` | fling velocity on the horizontal axis |
| `int velocityY` | fling velocity on the vertical axis |

| Returns |
|---|---|
| `int` | the target adapter position to you want to snap or `https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView#NO_POSITION()` if no snapping should happen |

### onFling

Added in [1.4.0](https://developer.android.com/jetpack/androidx/releases/recyclerview#1.4.0)

```
public boolean onFling(int velocityX, int velocityY)
```

Override this to handle a fling given the velocities in both x and y directions. Note that this method will only be called if the associated `https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView.LayoutManager` supports scrolling and the fling is not handled by nested scrolls first.

| Parameters |
|---|---|
| `int velocityX` | the fling velocity on the X axis |
| `int velocityY` | the fling velocity on the Y axis |

| Returns |
|---|---|
| `boolean` | true if the fling was handled, false otherwise. |

## Protected methods

### createScroller

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/recyclerview#1.0.0)

```
protected @Nullable RecyclerView.SmoothScroller createScroller(@NonNull RecyclerView.LayoutManager layoutManager)
```

Creates a scroller to be used in the snapping implementation.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView.LayoutManager layoutManager` | The `https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView.LayoutManager` associated with the attached `https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView`. |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/Nullable https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView.SmoothScroller` | a `https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView.SmoothScroller` which will handle the scrolling. |

### createSnapScroller

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/recyclerview#1.0.0) Deprecated in [1.0.0](https://developer.android.com/jetpack/androidx/releases/recyclerview#1.0.0)

```
protected @Nullable LinearSmoothScroller [createSnapScroller](https://developer.android.com/reference/androidx/recyclerview/widget/SnapHelper#createSnapScroller(androidx.recyclerview.widget.RecyclerView.LayoutManager))(@NonNull RecyclerView.LayoutManager layoutManager)
```

> [!CAUTION]
> **This method is deprecated.**   
>
> use `https://developer.android.com/reference/androidx/recyclerview/widget/SnapHelper#createScroller(androidx.recyclerview.widget.RecyclerView.LayoutManager)` instead.

Creates a scroller to be used in the snapping implementation.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView.LayoutManager layoutManager` | The `https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView.LayoutManager` associated with the attached `https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView`. |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/Nullable https://developer.android.com/reference/androidx/recyclerview/widget/LinearSmoothScroller` | a `https://developer.android.com/reference/androidx/recyclerview/widget/LinearSmoothScroller` which will handle the scrolling. |