airbnb / epoxy

Epoxy Epoxy is an Android library for building complex screens in a RecyclerView. Models are automatically generated from custom views or databinding layouts via annotation processing. These models are then used in an EpoxyController to declare what items to show in the RecyclerView. This abstracts the boilerplate of view holders, diffing items and binding payload changes, item types, item ids, span counts, and more, in order to simplify building screens with multiple view types. Additionally, Epoxy adds support for saving view state and automatic diffing of item changes. We developed Epoxy at Airbnb to simplify the process of working with RecyclerViews, and to add the missing functionality we needed. We now use Epoxy for most of the main screens in our app and it has improved our developer experience greatly. • Installation • Basic Usage • Documentation • Min SDK • Contributing • Sample App Installation Gradle is the only supported build configuration, so just add the dependency to your project file: Replace the variable with the latest version : See the releases page for up to date release versions and details Kotlin with KAPT If you are using Kotlin with KAPT you should also add so that annotations work properly. More information here Also, make sure to use instead of in your dependencies in the file. Kotlin with KSP (Recommended) KSP (Kotlin Symbol Processing) is recommended over KAPT as it is significantly faster. Add the KSP plugin to your root : Then apply it in your module's : You can configure KSP processor options: **Important:** DataBinding models are **not supported** with KSP, as Android's DataBinding library itself uses KAPT. If you need DataBinding support, you must continue using KAPT. For custom views with or ViewHolder models, KSP works perfectly. See the epoxy-kspsample module for a complete working example. Library Projects If you are using layout resources in Epoxy annotations then for library projects add Butterknife's gradle plugin to your . and then apply it in your module: Now make sure you use R2 instead of R inside all Epoxy annotations. This is not necessary if you don't use resources as annotation parameters, such as with custom view models. Basic Usage There are two main components of Epoxy: • The s that describe how your views should be displayed in the RecyclerView. • The where the models are used to describe what items to show and with what data. Creating Models Epoxy generates models for you based on your view or layout. Generated model classes are suffixed with an underscore ( ) are used directly in your EpoxyController classes. From Custom Views Add the annotation on a view class. Then, add a "prop" annotation on each setter method to mark it as a property for the model. A is then generated in the same package. More Details From DataBinding If you use Android DataBinding you can simply set up your xml layouts like normal: Then, create an interface or class in any package and add an annotation to declare your databinding layouts. From this layout name Epoxy generates a . More Details From ViewHolders If you use xml layouts without databinding you can create a model class to do the binding. A class is generated that subclasses HeaderModel and implements the model details. More Details Using your models in a controller A controller defines what items should be shown in the RecyclerView, by adding the corresponding models in the desired order. The controller's method declares which items to show. You are responsible for calling whenever your data changes, which triggers to run again. Epoxy tracks changes in the models and automatically binds and updates views. As an example, our shows a header, a list of photos, and a loader (if more photos are being loaded). The controller's method is called whenever photos are loaded, which triggers a call to so models representing the state of the new data can be built. Or with Kotlin An extension function is generated for each model so we can write this: Integrating with RecyclerView Get the backing adapter off the EpoxyController to set up your RecyclerView: If you are using the EpoxyRecyclerView integration is easier. Kotlin Or use Kotlin Extensions to simplify further and remove the need for a controller class. More Reading And that's it! The controller's declarative style makes it very easy to visualize what the RecyclerView will look like, even when many different view types or items are used. Epoxy handles everything else. If a view only partially changes, such as the description, only that new value is set on the view, so the system is very efficient Epoxy handles much more than these basics, and is highly configurable. See the wiki for in depth documentation. Documentation See examples and browse complete documentation at the Epoxy Wiki If you still have questions, feel free to create a new issue. Min SDK We support a minimum SDK of 14. However, Epoxy is based on the v7 support libraries so it should work with lower versions if you care to override the min sdk level in the manifest. Contributing Pull requests are welcome! We'd love help improving this library. Feel free to browse through open issues to look for things that need work. If you have a feature request or bug, please open a new issue so we can track it. License