# 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)

*** ** * ** ***

<br />

```
abstract class SnapHelper : RecyclerView.OnFlingListener
```

<br />

|---|---|---|
| [kotlin.Any](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html) |||
| ↳ | [androidx.recyclerview.widget.RecyclerView.OnFlingListener](https://developer.android.com/reference/kotlin/androidx/recyclerview/widget/RecyclerView.OnFlingListener) ||
|   | ↳ | [androidx.recyclerview.widget.SnapHelper](https://developer.android.com/reference/kotlin/androidx/recyclerview/widget/SnapHelper) |

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

|---|---|
| `https://developer.android.com/reference/kotlin/androidx/recyclerview/widget/LinearSnapHelper` | Implementation of the `https://developer.android.com/reference/kotlin/androidx/recyclerview/widget/SnapHelper` supporting snapping in either vertical or horizontal orientation. |
| `https://developer.android.com/reference/kotlin/androidx/recyclerview/widget/PagerSnapHelper` | Implementation of the `https://developer.android.com/reference/kotlin/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/kotlin/androidx/recyclerview/widget/RecyclerView`.

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

## Summary

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

| ### Public functions |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/recyclerview/widget/SnapHelper#attachToRecyclerView(androidx.recyclerview.widget.RecyclerView)(recyclerView: https://developer.android.com/reference/kotlin/androidx/recyclerview/widget/RecyclerView?)` Attaches the `https://developer.android.com/reference/kotlin/androidx/recyclerview/widget/SnapHelper` to the provided RecyclerView, by calling `https://developer.android.com/reference/kotlin/androidx/recyclerview/widget/RecyclerView#setOnFlingListener(androidx.recyclerview.widget.RecyclerView.OnFlingListener)`. |
| `abstract https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-array/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html>?` | `https://developer.android.com/reference/kotlin/androidx/recyclerview/widget/SnapHelper#calculateDistanceToFinalSnap(androidx.recyclerview.widget.RecyclerView.LayoutManager,android.view.View)( layoutManager: https://developer.android.com/reference/kotlin/androidx/recyclerview/widget/RecyclerView.LayoutManager, targetView: https://developer.android.com/reference/android/view/View.html )` Override this method to snap to a particular point within the target view or the container view on any axis. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-array/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html>!` | `https://developer.android.com/reference/kotlin/androidx/recyclerview/widget/SnapHelper#calculateScrollDistance(int,int)(velocityX: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, velocityY: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html)` Calculated the estimated scroll distance in each direction given velocities on both axes. |
| `abstract https://developer.android.com/reference/android/view/View.html?` | `https://developer.android.com/reference/kotlin/androidx/recyclerview/widget/SnapHelper#findSnapView(androidx.recyclerview.widget.RecyclerView.LayoutManager)(layoutManager: https://developer.android.com/reference/kotlin/androidx/recyclerview/widget/RecyclerView.LayoutManager!)` Override this method to provide a particular target view for snapping. |
| `abstract https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | `https://developer.android.com/reference/kotlin/androidx/recyclerview/widget/SnapHelper#findTargetSnapPosition(androidx.recyclerview.widget.RecyclerView.LayoutManager,int,int)( layoutManager: https://developer.android.com/reference/kotlin/androidx/recyclerview/widget/RecyclerView.LayoutManager!, velocityX: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, velocityY: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html )` Override to provide a particular adapter target position for snapping. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/recyclerview/widget/SnapHelper#onFling(int,int)(velocityX: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, velocityY: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html)` Override this to handle a fling given the velocities in both x and y directions. |

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

## Public constructors

### SnapHelper

Added in 1.0.0

```
SnapHelper()
```

## Public functions

### attachToRecyclerView

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

```
fun attachToRecyclerView(recyclerView: RecyclerView?): Unit
```

Attaches the `https://developer.android.com/reference/kotlin/androidx/recyclerview/widget/SnapHelper` to the provided RecyclerView, by calling `https://developer.android.com/reference/kotlin/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 |
|---|---|
| `recyclerView: https://developer.android.com/reference/kotlin/androidx/recyclerview/widget/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/kotlin/androidx/recyclerview/widget/RecyclerView.OnFlingListener` attached to the provided `https://developer.android.com/reference/kotlin/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)

```
abstract fun calculateDistanceToFinalSnap(
    layoutManager: RecyclerView.LayoutManager,
    targetView: View
): Array<Int>?
```

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/kotlin/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 |
|---|---|
| `layoutManager: https://developer.android.com/reference/kotlin/androidx/recyclerview/widget/RecyclerView.LayoutManager` | the `https://developer.android.com/reference/kotlin/androidx/recyclerview/widget/RecyclerView.LayoutManager` associated with the attached `https://developer.android.com/reference/kotlin/androidx/recyclerview/widget/RecyclerView` |
| `targetView: https://developer.android.com/reference/android/view/View.html` | the target view that is chosen as the view to snap |

| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-array/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html>?` | 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)

```
fun calculateScrollDistance(velocityX: Int, velocityY: Int): Array<Int>!
```

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

| Parameters |
|---|---|
| `velocityX: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | Fling velocity on the horizontal axis. |
| `velocityY: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | Fling velocity on the vertical axis. |

| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-array/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html>!` | 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)

```
abstract fun findSnapView(layoutManager: RecyclerView.LayoutManager!): View?
```

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

This method is called when the `https://developer.android.com/reference/kotlin/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/kotlin/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 |
|---|---|
| `layoutManager: https://developer.android.com/reference/kotlin/androidx/recyclerview/widget/RecyclerView.LayoutManager!` | the `https://developer.android.com/reference/kotlin/androidx/recyclerview/widget/RecyclerView.LayoutManager` associated with the attached `https://developer.android.com/reference/kotlin/androidx/recyclerview/widget/RecyclerView` |

| Returns |
|---|---|
| `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)

```
abstract fun findTargetSnapPosition(
    layoutManager: RecyclerView.LayoutManager!,
    velocityX: Int,
    velocityY: Int
): Int
```

Override to provide a particular adapter target position for snapping.

| Parameters |
|---|---|
| `layoutManager: https://developer.android.com/reference/kotlin/androidx/recyclerview/widget/RecyclerView.LayoutManager!` | the `https://developer.android.com/reference/kotlin/androidx/recyclerview/widget/RecyclerView.LayoutManager` associated with the attached `https://developer.android.com/reference/kotlin/androidx/recyclerview/widget/RecyclerView` |
| `velocityX: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | fling velocity on the horizontal axis |
| `velocityY: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | fling velocity on the vertical axis |

| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | the target adapter position to you want to snap or `https://developer.android.com/reference/kotlin/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)

```
fun onFling(velocityX: Int, velocityY: Int): Boolean
```

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/kotlin/androidx/recyclerview/widget/RecyclerView.LayoutManager` supports scrolling and the fling is not handled by nested scrolls first.

| Parameters |
|---|---|
| `velocityX: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | the fling velocity on the X axis |
| `velocityY: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | the fling velocity on the Y axis |

| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | true if the fling was handled, false otherwise. |

## Protected functions

### createScroller

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

```
protected fun createScroller(layoutManager: RecyclerView.LayoutManager): RecyclerView.SmoothScroller?
```

Creates a scroller to be used in the snapping implementation.

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

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/recyclerview/widget/RecyclerView.SmoothScroller?` | a `https://developer.android.com/reference/kotlin/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 fun [createSnapScroller](https://developer.android.com/reference/kotlin/androidx/recyclerview/widget/SnapHelper#createSnapScroller(androidx.recyclerview.widget.RecyclerView.LayoutManager))(layoutManager: RecyclerView.LayoutManager): LinearSmoothScroller?
```

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

Creates a scroller to be used in the snapping implementation.

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

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