Skip to content

Getting started

Add the following dependency to your app's build.gradle:

implementation "com.rubensousa.dpadrecyclerview:dpadrecyclerview:1.4.0"

// Recommended: To use Compose together with DpadRecyclerView
implementation "com.rubensousa.dpadrecyclerview:dpadrecyclerview-compose:1.4.0"

// Optional: Espresso test helpers for your instrumented tests:
androidTestImplementation "com.rubensousa.dpadrecyclerview:dpadrecyclerview-testing:1.4.0"

Basic setup

Since DpadRecyclerView is a custom view that extends from RecyclerView, you just need to add it to your XML layout as any other view:

1
2
3
4
5
<com.rubensousa.dpadrecyclerview.DpadRecyclerView
    android:id="@+id/recyclerView"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="vertical" />

Warning

Don't set a LayoutManager because DpadRecyclerView already assigns one internally.

Follow the official RecyclerView guides to render Views on the screen or use any RecyclerView library as you would for mobile apps.

You can also render Composables inside using the dpadrecyclerview-compose library.

Observe selection changes

You can observe selection changes using the following:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
recyclerView.addOnViewHolderSelectedListener(object : OnViewHolderSelectedListener {
    override fun onViewHolderSelected(
        parent: RecyclerView,
        child: RecyclerView.ViewHolder?,
        position: Int,
        subPosition: Int
    ) {}

    override fun onViewHolderSelectedAndAligned(
        parent: RecyclerView,
        child: RecyclerView.ViewHolder?,
        position: Int,
        subPosition: Int
    ) {}
})

Observe focus changes

To react to focus changes, use this:

1
2
3
4
5
6
7
8
recyclerView.addOnViewFocusedListener(object : OnViewFocusedListener {
    override fun onViewFocused(
        parent: RecyclerView.ViewHolder,
        child: View,
    ) {
        // Child is now focused
    }
})

How to use with Compose

Check this page to see more some examples with Compose

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
@Composable
fun ItemComposable(
    item: Int, 
    onClick: () -> Unit,
    modifier: Modifier = Modifier,
) {
    var isFocused by remember { mutableStateOf(false) }
    val backgroundColor = if (isFocused) Color.White else Color.Black
    val textColor = if (isFocused) Color.Black else Color.White
    Box(
        modifier = modifier
            .background(backgroundColor)
            .onFocusChanged { focusState ->
                isFocused = focusState.hasFocus
            }
             .focusable()
            .dpadClickable {
                onClick()
            },
        contentAlignment = Alignment.Center,
    ) {
        Text(
            text = item.toString(),
            color = textColor,
            fontSize = 35.sp
        )
    }
}

More customizations

Check the following recipes:

  1. Layout: for defining the type of layout (linear or grid) or to enable infinite carousels
  2. Spacing: add spacing between items
  3. Alignment: align items to different regions of the screen
  4. Focus: configure how focus is handled
  5. Scrolling: configure the scrolling speed

Sample

The sample on Github contains a complete example of how to use this library.