{"id":16526109,"url":"https://github.com/markusressel/kutepreferences","last_synced_at":"2025-10-26T02:44:59.770Z","repository":{"id":52845789,"uuid":"129962741","full_name":"markusressel/KutePreferences","owner":"markusressel","description":"A beautiful, clean and extendable preferences library for Android written in Kotlin","archived":false,"fork":false,"pushed_at":"2024-09-09T23:29:17.000Z","size":1642,"stargazers_count":12,"open_issues_count":9,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-10-12T17:25:43.767Z","etag":null,"topics":["android","android-compose","android-library","compose","gui","gui-library","hacktoberfest","jetpack-compose","kotlin","kotlin-android","library","preferences","settings"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/markusressel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-17T20:42:27.000Z","updated_at":"2024-08-28T23:00:07.000Z","dependencies_parsed_at":"2024-03-19T00:31:47.624Z","dependency_job_id":"f252acf2-f417-4ac9-a32a-c9970ea16c26","html_url":"https://github.com/markusressel/KutePreferences","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markusressel%2FKutePreferences","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markusressel%2FKutePreferences/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markusressel%2FKutePreferences/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markusressel%2FKutePreferences/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/markusressel","download_url":"https://codeload.github.com/markusressel/KutePreferences/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221813471,"owners_count":16884833,"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":["android","android-compose","android-library","compose","gui","gui-library","hacktoberfest","jetpack-compose","kotlin","kotlin-android","library","preferences","settings"],"created_at":"2024-10-11T17:26:07.395Z","updated_at":"2025-10-26T02:44:59.676Z","avatar_url":"https://github.com/markusressel.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# KutePreferences | [![codebeat badge](https://codebeat.co/badges/418ec567-fa53-4f97-ad98-eb8c4bb816ec)](https://codebeat.co/projects/github-com-markusressel-kutepreferences-master) |\n\nA Material Design 3 **GUI** library for easy to use, fast and beautiful **preferences** in your app.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/markusressel/KutePreferences/master/.images/main_light.png\" width=\"400\"\u003e \u003cimg src=\"https://raw.githubusercontent.com/markusressel/KutePreferences/master/.images/main_dark.png\" width=\"400\"\u003e \n\u003c/p\u003e\n\n# Features\n\n* [x] Material Design 3\n* [x] Easy to use\n* [x] Many included preference types\n* [x] Expandable with custom styles and logic\n* [x] Integrated search\n* [x] Persistence\n* [x] Written entirely in Kotlin \u0026 Compose\n\n# How to use\n\nHave a look at the demo app (```app```  module) for a complete sample. The sample app uses **Dagger 2** (Hilt) for\nDependency Injection but this is not a requirement.\n\n## Gradle\n\nTo use this library just include it in your dependencies using\n\n```groovy\nrepositories {\n    ...\n    maven { url \"https://jitpack.io\" }\n}\n```\n\nin your project build.gradle file and\n\n```groovy\ndependencies {\n    ...\n\n    def kutePreferencesVersion = \"v3.0.0\"\n    // choose the ones you need\n    implementation(\"com.github.markusressel.KutePreferences:core:${kutePreferencesVersion}\")\n    implementation(\"com.github.markusressel.KutePreferences:ui:${kutePreferencesVersion}\")\n}\n```\n\nin your desired module `build.gradle` file.\n\n## Create a KutePreferences ViewModel\n\nSince **KutePreferences** provides navigation between categories, search and other things, you have to create a\nViewModel for your preferences and extend the provided `KutePreferencesViewModel`. Make sure to call the\n`initPreferenceTree()` to setup the items that should be shown:\n\n```kotlin\nclass YourPreferencesViewModel(\n    navigator: KuteNavigator,\n) : KutePreferencesViewModel(navigator) {\n\n    private val dataProvider by lazy {\n        DefaultKutePreferenceDataProvider(context)\n    }\n\n    init {\n        val preferenceTree = createPreferenceTree()\n        initPreferencesTree(preferenceTree)\n    }\n\n    private fun createPreferenceTree(): List\u003cKutePreferenceListItem\u003e {\n        return listOf(\n            KuteTextPreference(\n                key = R.string.key_demo_text_pref,\n                title = R.string.title_demo_text_pref,\n                defaultValue = \"\",\n                dataProvider = dataProvider\n            )\n        )\n    }\n}\n```\n\n## Structure\n\nThe items that you return in the `initPreferenceTree()` method are a direct representation of the categories, sections\npreferences and custom items that will be visible in your app. Items that need persistence require a `KuteDataProvider`\nparameter that defines how the current state of the preference item is persisted.\n\n### Preference Types\n\nKutePreferences includes implementation for most of the commonly needed preference items that you might encounter when\nbuilding an app.\n\n| Name                         | Item Type              | Description                                                                                                       |\n|------------------------------|------------------------|-------------------------------------------------------------------------------------------------------------------|\n| `KuteBooleanPreference`      | `Boolean`              | A simple on/off preference.                                                                                       |\n| `KuteTextPreference`         | `String`               | A simple text preference.                                                                                         |\n| `KuteUrlPreference`          | `String`               | A url preference.                                                                                                 |\n| `KutePasswordPreference`     | `String`               | A password text preference. This type works exactly like `KuteTextPreference` but includes obscuring typed input. |\n| `KuteNumberPreference`       | `Integer`              | A preference for number values.                                                                                   |\n| `KuteSliderPreference`       | `Integer`              | Like `KuteNumberPreference` but with a slider GUI instead of a direct input field.                                |\n| `KuteFloatRangePreference`   | `Integer`              | A preference for a number range.                                                                                  |\n| `KuteDatePreference`         | `Date`                 | Let's the user select and store a date.                                                                           |\n| `KuteTimePreference`         | `TimePersistenceModel` | Let's the user select and store a time of the day.                                                                |\n| `KuteColorPreference`        | `Color`                | Let's the user select and store an ARGB color.                                                                    |\n| `KuteSingleSelectPreference` | `List\u003cT\u003e`              | Allows a single selection from a specified list of items.                                                         |\n| `KuteMultiSelectPreference`  | `List\u003cT\u003e`              | Allows to select multiple items from a specified list of items.                                                   |\n\n### Other Types\n\nIf you want to implement other list items that don't need any persistence you can use one of these implementations:\n\n| Name         | Description                                   |\n|--------------|-----------------------------------------------|\n| `KuteAction` | A simple `click` action provided with a name. |\n\n### Grouping\n\nFor better context preference items can be grouped in categories or divided by simple headlines. To do this you can use\none of these classes:\n\n| Name           | Description                                                               |\n|----------------|---------------------------------------------------------------------------|\n| `KuteCategory` | A category groups sections, preference items and/or other category items. |\n| `KuteSection`  | A group of preference items inside a single preference category.          |\n\n## Render the UI\n\nAt the location of choice use the `KutePreferencesTheme` together with the `KuteOverview` and pass the preferences tree\nto it:\n\n```kotlin\nKutePreferencesTheme {\n    val currentItems by vm.currentPreferenceItems.collectAsState(initial = emptyList())\n\n    KutePreferencesScreen(\n        modifier = Modifier.fillMaxSize(),\n        items = currentItems\n    )\n}\n```\n\n### Theming\n\nKutePreferences is based on Material Design 3 by default, and will automatically inherit the styling of your app (if you\nuse MD3 in you app). You can override the styling by passing colors to the `KutePreferencesTheme`:\n\n```kotlin\nval defaultColors = defaultColors()\nKutePreferencesTheme(\n    colors = defaultColors.copy(\n        category = defaultColors.category.copy(\n            titleColor = Color.Red\n        )\n    )\n) {\n    ...\n}\n```\n\n## Implement custom preferences\n\nTo implement a custom type, first create a class that implements\nthe [KutePreferenceListItem](core/src/main/java/de/markusressel/kutepreferences/core/preference/KutePreferenceListItem.kt)\ninterface. Take a look at\nthe [CustomPreference](app/src/main/java/de/markusressel/kutepreferences/demo/domain/CustomPreference.kt)\nfor a complete example. If it fits your needs\nthe [KutePreferenceItem](core/src/main/java/de/markusressel/kutepreferences/core/preference/KutePreferenceItem.kt) base\nclass can be used instead of implementing everything from scratch (which has some basic functionality implemented\nalready).\n\nImportant things to keep in mind if you implement your own preference item:\n\n* remember to update the description of a preference item to always reflect the currently persisted value\n* when defining layouts remember to use theme values from the `LocalKuteColors.current` object\n* to replicate the look of a \"default list item\", use the `DefaultPreferenceListItem` composable\n\n### Register Custom Types\n\nKutePreferences already has built-in types for most of the commonly required preferences. If you need change/override an\nexisting type, or create a completely custom one, you can register your own like this:\n\n```kotlin\nclass YourPreferencesViewModel(...) : KutePreferencesViewModel(navigator) {\n\n    init {\n        KuteStyleManager.registerTypeHook { listItem -\u003e\n            when (listItem) {\n                is YourCustomPreference -\u003e {\n                    YourCustomPreferenceView(listItem)\n                    true\n                }\n                else -\u003e false\n            }\n        }\n\n        ...\n    }\n}\n```\n\n# Troubleshooting\n\n## Navigation\n\n* The back button doesn't work\n    * ensure that you are calling the `kuteNavigator.goBack()` method when a back press is registered\n      by the activity that is hosting it (like seen in the example app)\n\n# Contributing\n\nGitHub is for social coding: if you want to write code, I encourage contributions through pull requests from forks of\nthis repository. Create GitHub tickets for bugs and new features and comment on the ones that you are interested in.\n\n# License\n\n```\n\nMIT License\n\nCopyright (c) 2018 Markus Ressel\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkusressel%2Fkutepreferences","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarkusressel%2Fkutepreferences","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkusressel%2Fkutepreferences/lists"}