You can customize the RecyclerView
objects to
meet your specific needs. The standard classes described in
Create dynamic lists with
RecyclerView provide all the functionality
that most developers will need; in many cases, the only customization you need
to do is design the view for each view holder and write the code to update
those views with the appropriate data. However, if your app has specific
requirements, you can modify the standard behavior in a number of ways. This
page describes some of the other possible customizations.
Modifying the layout
The RecyclerView
uses a layout manager to
position the individual items on the screen and determine when to reuse item views that are no
longer visible to the user. To reuse (or recycle) a view, a layout manager may ask the
adapter to replace the contents of the view with a different element from the dataset. Recycling
views in this manner improves performance by avoiding the creation of unnecessary views or
performing expensive findViewById()
lookups. The Android
Support Library includes three standard layout managers, each of which offers many customization
options:
LinearLayoutManager
arranges the items in a one-dimensional list. Using aRecyclerView
withLinearLayoutManager
provides functionality like the olderListView
layout.GridLayoutManager
arranges the items in a two-dimensional grid, like the squares on a checkerboard. Using aRecyclerView
withGridLayoutManager
provides functionality like the olderGridView
layout.StaggeredGridLayoutManager
arranges the items in a two-dimensional grid, with each column slightly offset from the one before, like the stars in an American flag.
If none of these layout managers suits your needs, you can create your own by
extending the RecyclerView.LayoutManager
abstract class.
Add item animations
Whenever an item changes, the RecyclerView
uses an animator to change its appearance. This animator is an object that
extends the abstract RecyclerView.ItemAnimator
class. By default, the
RecyclerView
uses DefaultItemAnimator
to
provide the animation. If you want to provide custom animations, you can define
your own animator object by extending RecyclerView.ItemAnimator
.
Enable list-item selection
The
recyclerview-selection
library enables users to select items in
RecyclerView
list using touch or mouse input.
You retain control over the visual presentation of a selected item. You
can also retain control over policies controlling selection behavior, such as
items that can be eligible for selection, and how many items can be selected.
To add selection support to a RecyclerView
instance, follow these steps:
- Determine which selection key type to use, then build a
ItemKeyProvider
.There are three key types that you can use to identify selected items:
Parcelable
(and all subclasses likeUri
),String
, andLong
. For detailed information about selection-key types, seeSelectionTracker.Builder
. - Implement
ItemDetailsLookup
. - Update item
Views
inRecyclerView
to reflect that the user has selected or unselected it.The selection library does not provide a default visual decoration for the selected items. You must provide this when you implement
onBindViewHolder()
. The recommended approach is as follows:- In
onBindViewHolder()
, callsetActivated()
(notsetSelected()
) on theView
object withtrue
orfalse
(depending on if the item is selected). - Update the styling of the view to represent the activated status. We recommend you use a color state list resource to configure the styling.
- In
- Use
ActionMode
to provide the user with tools to perform an action on the selection. - Perform any interpreted secondary actions
- Assemble everything with
SelectionTracker.Builder
- Include selection in the activity lifecycle events.
ItemDetailsLookup
enables the selection library to access information about
RecyclerView
items given a
MotionEvent
.
It is effectively a factory for
ItemDetails
instances that are backed up by (or extracted from) a
RecyclerView.ViewHolder
instance.
Register a SelectionTracker.SelectionObserver
to be notified when selection changes. When a selection is first created,
start ActionMode
to represent this to the
user, and provide selection-specific actions. For example, you may add a
delete button to the ActionMode
bar, and
connect the back arrow on the bar to clear the selection. When the selection
becomes empty (if the user cleared the selection the last time), don't
forget to terminate action mode.
At the end of the event processing pipeline, the library may determine that
the user is attempting to activate an item by tapping it, or is attempting
to drag and drop an item or set of selected items. React to these
interpretations by registering the appropriate listener. For more
information, see
SelectionTracker.Builder
.
The following example shows how to put these pieces together by using the
Long
selection key:
Kotlin
var tracker = SelectionTracker.Builder( "my-selection-id", recyclerView, StableIdKeyProvider(recyclerView), MyDetailsLookup(recyclerView), StorageStrategy.createLongStorage()) .withOnItemActivatedListener(myItemActivatedListener) .build()
Java
SelectionTracker tracker = new SelectionTracker.Builder<>( "my-selection-id", recyclerView, new StableIdKeyProvider(recyclerView), new MyDetailsLookup(recyclerView), StorageStrategy.createLongStorage()) .withOnItemActivatedListener(myItemActivatedListener) .build();
In order to build a
SelectionTracker
instance, your app must supply the same
RecyclerView.Adapter
that you used to
initialize RecyclerView
to
SelectionTracker.Builder
.
For this reason, you will most likely need to inject the
SelectionTracker
instance, once created, into your
RecyclerView.Adapter
after the
RecyclerView.Adapter
is
created. Otherwise, you won't be able to check an item's selected status from
the
onBindViewHolder()
method.
In order to preserve selection state across the
activity lifecycle
events, your app must call the selection tracker's
onSaveInstanceState()
and
onRestoreInstanceState()
methods from the activity's
onSaveInstanceState()
and
onRestoreInstanceState()
methods respectively. Your app must also supply a unique selection ID to the
SelectionTracker.Builder
constructor. This ID is required because an activity or a fragment may have
more than one distinct, selectable list, all of which need to be persisted
in their saved state.
Additional resources
RecyclerView
is
used in the Sunflower demo app.