{"id":13604535,"url":"https://github.com/lisawray/groupie","last_synced_at":"2025-05-14T18:04:26.947Z","repository":{"id":37382260,"uuid":"67165904","full_name":"lisawray/groupie","owner":"lisawray","description":"Groupie helps you display and manage complex RecyclerView layouts.","archived":false,"fork":false,"pushed_at":"2023-10-03T04:12:10.000Z","size":678,"stargazers_count":3668,"open_issues_count":70,"forks_count":291,"subscribers_count":69,"default_branch":"master","last_synced_at":"2025-05-12T11:07:16.595Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lisawray.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2016-09-01T20:59:35.000Z","updated_at":"2025-05-10T16:01:23.000Z","dependencies_parsed_at":"2024-01-14T11:09:36.201Z","dependency_job_id":"dd5742b3-18c9-421a-9890-922dd7b31a13","html_url":"https://github.com/lisawray/groupie","commit_stats":null,"previous_names":["genius/groupie"],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lisawray%2Fgroupie","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lisawray%2Fgroupie/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lisawray%2Fgroupie/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lisawray%2Fgroupie/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lisawray","download_url":"https://codeload.github.com/lisawray/groupie/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254190397,"owners_count":22029632,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T19:00:47.435Z","updated_at":"2025-05-14T18:04:26.905Z","avatar_url":"https://github.com/lisawray.png","language":"Java","funding_links":[],"categories":["Java"],"sub_categories":[],"readme":"# groupie\n\nGroupie is a simple, flexible library for complex RecyclerView layouts.  \n\nGroupie lets you treat your content as logical groups and handles change notifications for you -- think sections with headers and footers, expandable groups, blocks of vertical columns, and much more.  It makes it easy to handle asynchronous content updates and insertions and user-driven content changes.  At the item level, it abstracts the boilerplate of item view types, item layouts, viewholders, and span sizes.  \n \n\u003cimg src=\"http://i.imgur.com/eftOE0v.gif\" width=\"300px\"/\u003e\n\n# Try it out:\n\n```gradle\nimplementation \"com.github.lisawray.groupie:groupie:$groupie_version\"\n```\n\nGroupie also has a support module for Android's [view binding](https://developer.android.com/topic/libraries/view-binding). This module also supports Android [data binding](https://developer.android.com/topic/libraries/data-binding/index.html), so if your project uses both data binding and view binding, you don't have to add the dependency on the data binding support module. [Setup here.](#view-binding)\n\n```gradle\nimplementation \"com.github.lisawray.groupie:groupie:$groupie_version\"\nimplementation \"com.github.lisawray.groupie:groupie-viewbinding:$groupie_version\" \n```\n\n### Note:\nIf using `groupie-viewbinding` in a databinding project is only available when using Android Gradle Plugin 3.6.0 or higher.\n\nIf using an older Gradle Plugin version with databinding the you can use the standalone `groupie-databinding` library to generate view holders. [Setup here.](#data-binding)\n\n```gradle\nimplementation \"com.github.lisawray.groupie:groupie:$groupie_version\"\nimplementation \"com.github.lisawray.groupie:groupie-databinding:$groupie_version\" \n```\n\nYou can also use Groupie with Java and your existing ViewHolders. \n\nWhich one to choose?  It's up to you and what your project already uses. You can even use Kotlin and data binding together.[\u003csup\u003e*\u003c/sup\u003e](#kotlin-and-data-binding) Or all your existing hand-written Java ViewHolders, and one new Kotlin item to try it out. Go crazy!  \n    \n## Get started\n\nUse a `GroupieAdapter` anywhere you would normally use a `RecyclerView.Adapter`, and attach it to your RecyclerView as usual.\n\nKotlin\n```kotlin\nval adapter = GroupieAdapter()\nrecyclerView.adapter = adapter\n```\n\nJava\n```java\nGroupieAdapter adapter = new GroupieAdapter();\nrecyclerView.setAdapter(adapter);\n```\n    \n## Groups\n\nGroups are the building block of Groupie.  An individual `Item` (the unit which an adapter inflates and recycles) is a Group of 1.  You can add Groups and Items interchangeably to the adapter.\n\nKotlin\n```kotlin\ngroupAdapter += HeaderItem()\ngroupAdapter += CommentItem()\n\nval section = Section()\nsection.setHeader(HeaderItem())\nsection.addAll(bodyItems)\ngroupAdapter += section\n```\n\nJava\n```java\ngroupAdapter.add(new HeaderItem());\ngroupAdapter.add(new CommentItem());\n\nSection section = new Section();\nsection.setHeader(new HeaderItem());\nsection.addAll(bodyItems);\ngroupAdapter.add(section);\n```\n    \nModifying the contents of the GroupieAdapter in any way automatically sends change notifications.  Adding an item calls `notifyItemAdded()`; adding a group calls `notifyItemRangeAdded()`, etc.\n\nModifying the contents of a Group automatically notifies its parent.  When notifications reach the GroupieAdapter, it dispatches final change notifications.  There's never a need to manually notify or keep track of indices, no matter how you structure your data.\n\n```java\nsection.removeHeader(); // results in a remove event for 1 item in the adapter, at position 2\n```\n    \nThere are a few simple implementations of Groups within the library:\n- `Section`, a list of body content with an optional header group and footer group.  It supports diffing and animating moves, updates and other changes\n- `ExpandableGroup`, a single parent group with a list of body content that can be toggled hidden or shown.\n    \nGroupie tries not to assume what features your groups require.  Instead, groups are flexible and composable.  They can be combined and nested to arbitrary depth.  \n    \nLife (and mobile design) is complicated, so groups are designed so that making new ones and defining their behavior is easy. You should make many small, simple, custom groups as the need strikes you.\n\nYou can implement the `Group` interface directly if you want.  However, in most cases, you can extend `Section` or the base implementation, `NestedGroup`.  Section supports common RV paradigms like diffing, headers, footers, and placeholders.  NestedGroup provides support for arbitrary nesting of groups, registering/unregistering listeners, and fine-grained change notifications to support animations and updating the adapter.\n    \n## Items\n\nGroupie abstracts away the complexity of multiple item view types.  Each Item declares a view layout id, and gets a callback to `bind` the inflated layout.  That's all you need; you can add your new item directly to a `GroupieAdapter` and call it a day.\n\n### Item with data binding:\n\nThe `Item` class gives you simple callbacks to bind your model object to the generated binding.  Because of data binding, there's no need to write a view holder.  \n\n```java\npublic class SongItem extends BindableItem\u003cSongBinding\u003e {\n\n    public SongItem(Song song) {\n        this(song);\n    }    \n\n    @Override public void bind(SongBinding binding, int position) {\n        binding.setSong(song);\n    }\n\n    @Override public int getLayout() {\n        return R.layout.song;\n    }\n}\n```\n\nIf you're converting existing ViewHolders, you can reference any named views (e.g. `R.id.title`) directly from the binding instead. \n```java\n    @Override public void bind(SongBinding binding, int position) {\n        binding.title.setText(song.getTitle());\n    }\n```\n\nYou can also mix and match `BindableItem` and other `Items` in the adapter, so you can leave legacy viewholders as they are by making an `Item\u003cMyExistingViewHolder\u003e`.  \n\n### Legacy item (your own ViewHolder)\nYou can leave legacy viewholders as they are by converting `MyExistingViewHolder` to extend `GroupieViewHolder` rather than `RecyclerView.ViewHolder`. Make sure to change the imports to `com.xwray.groupie.Item` and `com.xwray.groupie.GroupieViewHolder`.\n\nFinally, in your `Item\u003cMyExistingViewHolder\u003e`, override \n\n```java\n    @Override\n    public MyExistingViewHolder createViewHolder(@NonNull View itemView) {\n        return new MyExistingViewHolder(itemView);\n    }\n```\n\n### Note: \n\nItems can also declare their own column span and whether they are draggable or swipeable.  \n\n# Gradle setup\n\n## Kotlin\n\nIn your project level `build.gradle` file, include:\n\n```\nbuildscript {\n    ext.kotlin_version = '1.6.21'\n\n    repositories {\n        mavenCentral()\n    }\n\n    dependencies {\n        classpath \"org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version\"\n    }\n}\n\nallprojects {\n    repositories {\n        google()\n        mavenCentral()\n        maven { url \"https://jitpack.io\" }\n    }\n}\n```\n\nIn new projects, the `settings.gradle` file has a `dependencyResolutionManagement` block, which needs to specify the repository as well:\n\n```\ndependencyResolutionManagement {\n    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)\n    repositories {\n        google()\n        mavenCentral()\n        maven { url 'https://jitpack.io' }  // \u003c--\n        jcenter() // Warning: this repository is going to shut down soon\n    }\n}\n```\n\nIn your app `build.gradle` file, include:\n\n```\nimplementation 'com.github.lisawray.groupie:groupie:$groupie_version'\n```\n\n## View binding\n\nAdd to your app module's `build.gradle`:\n\n```gradle\nandroid {\n    buildFeatures {\n        viewBinding true\n    }\n}\n\ndependencies {\n    implementation \"com.github.lisawray.groupie:groupie:$groupie_version\"\n    implementation \"com.github.lisawray.groupie:groupie-viewbinding:$groupie_version\"\n}\n```\n\nThen:\n\n```kotlin\nclass MyLayoutItem: BindableItem\u003cMyLayoutBinding\u003e() {\n    override fun initializeViewBinding(view: View): MyLayoutBinding {\n        return MyLayoutBinding.bind(view)\n    }\n\n    // Other implementations...\n}\n```\n\n### Note:\n\nIf you use `groupie-databinding` with data binding classes and your layouts have some variables or [observable objects](https://developer.android.com/topic/libraries/data-binding/observability), don't forget to run [`executePendingBindings`](https://developer.android.com/topic/libraries/data-binding/generated-binding#immediate_binding) at the last point in `bind`.\n\n## Data binding\n\nAdd to your app module's build.gradle:\n\n```gradle\nandroid {\n    buildFeatures {\n        dataBinding true\n    }\n}\n\ndependencies {\n    implementation \"com.github.lisawray.groupie:groupie:$groupie_version\"\n    implementation \"com.github.lisawray.groupie:groupie-databinding:$groupie_version\"\n}\n```\n\nThen, just wrap each item layout in `\u003clayout\u003e` tags.  (The `\u003cdata\u003e` section is optional.)  \n\n`layout/item_song.xml`\n```xml\n\u003clayout xmlns:android=\"http://schemas.android.com/apk/res/android\" \n    xmlns:tools=\"http://schemas.android.com/tools\"\u003e\n    \u003cdata\u003e\n        \u003cvariable name=\"song\" type=\"com.example.Song\" /\u003e\n    \u003c/data\u003e\n\n    \u003cFrameLayout \n        android:layout_width=\"match_parent\"\n        android:layout_height=\"wrap_content\" \u003e\n\n        \u003cTextView\n            android:id=\"@+id/title\"\n            android:layout_width=\"wrap_content\"\n            android:layout_height=\"wrap_content\"\n            android:layout_gravity=\"center\"\n            android:text=\"@{song.title}\"\n            tools:text=\"A Song Title\" /\u003e\n\n    \u003c/FrameLayout\u003e\n\u003c/layout\u003e\n```\n\nBindings are only generated for layouts wrapped with \u003clayout/\u003e tags, so there's no need to convert the rest of your project (unless you want to).\n\nYou can add a `\u003cdata\u003e` section to directly bind a model or ViewModel, but you don't have to.  The generated view bindings alone are a huge time saver.\n\n### Kotlin AND data binding / view binding?\nSure, why not?  Follow all the instructions from *both* sections above.\nYou only need to include the `groupie-databinding` or `groupie-viewbinding` dependency.\n\n# Contributing\nContributions you say?  Yes please!\n\n### Bug report? \n- If at all possible, please attach a *minimal* sample project or code which reproduces the bug. \n- Screenshots are also a huge help if the problem is visual.\n### Send a pull request!\n- If you're fixing a bug, please add a failing test or code that can reproduce the issue.\n\n\nIf you try it out, I'd love to know what you think. Please hit up Lisa at [first][last]@gmail.com or on Twitter at [@lisawrayz](https://twitter.com/lisawrayz).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flisawray%2Fgroupie","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flisawray%2Fgroupie","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flisawray%2Fgroupie/lists"}