{"id":18425655,"url":"https://github.com/zhanghai/composepreference","last_synced_at":"2025-04-04T14:03:09.116Z","repository":{"id":211039164,"uuid":"715053318","full_name":"zhanghai/ComposePreference","owner":"zhanghai","description":"Preference implementation for Jetpack Compose Material 3","archived":false,"fork":false,"pushed_at":"2024-11-15T08:40:24.000Z","size":585,"stargazers_count":229,"open_issues_count":3,"forks_count":9,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-28T13:04:37.012Z","etag":null,"topics":["android","android-library","android-ui","compose","compose-library","jetpack-compose","jetpack-compose-library","kotlin","kotlin-android","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":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zhanghai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing.md","funding":null,"license":"LICENSE","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":"2023-11-06T11:42:01.000Z","updated_at":"2025-03-26T22:24:13.000Z","dependencies_parsed_at":"2023-12-14T14:24:24.303Z","dependency_job_id":"29042285-add5-4636-b145-6c7b27542663","html_url":"https://github.com/zhanghai/ComposePreference","commit_stats":null,"previous_names":["zhanghai/composepreference"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhanghai%2FComposePreference","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhanghai%2FComposePreference/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhanghai%2FComposePreference/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhanghai%2FComposePreference/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zhanghai","download_url":"https://codeload.github.com/zhanghai/ComposePreference/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247184681,"owners_count":20897818,"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-library","android-ui","compose","compose-library","jetpack-compose","jetpack-compose-library","kotlin","kotlin-android","preferences","settings"],"created_at":"2024-11-06T05:04:45.188Z","updated_at":"2025-04-04T14:03:09.075Z","avatar_url":"https://github.com/zhanghai.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Compose Preference\n\n[![Android CI status](https://github.com/zhanghai/ComposePreference/workflows/Android%20CI/badge.svg)](https://github.com/zhanghai/ComposePreference/actions) [![GitHub release](https://img.shields.io/github/v/release/zhanghai/ComposePreference)](https://github.com/zhanghai/ComposePreference/releases) [![License](https://img.shields.io/github/license/zhanghai/ComposePreference?color=blue)](LICENSE)\n\n[Preference](https://developer.android.com/develop/ui/views/components/settings) implementation for [Jetpack Compose](https://developer.android.com/jetpack/compose) [Material 3](https://developer.android.com/jetpack/compose/designsystems/material3).\n\nThis is not an officially supported Google product.\n\n## Preview\n\n\u003cp\u003e\u003cimg src=\"fastlane/metadata/android/en-US/images/phoneScreenshots/1.png\" width=\"32%\" /\u003e \u003cimg src=\"fastlane/metadata/android/en-US/images/phoneScreenshots/2.png\" width=\"32%\" /\u003e\u003c/p\u003e\n\n## Integration\n\nGradle:\n\n```gradle\nimplementation 'me.zhanghai.compose.preference:library:1.1.1'\n```\n\n## Design\n\nThere is no official and complete Material 3 UX specification for preference yet, so the UX design of this library mainly comes from the following sources:\n\n- [Material Design 3](https://m3.material.io/)\n- [Material Design 2 Android Settings](https://m2.material.io/design/platform-guidance/android-settings.html)\n- [Android settings design guidelines](https://source.android.com/docs/core/settings/settings-guidelines)\n- [AndroidX Preference](https://developer.android.com/jetpack/androidx/releases/preference)\n- [AOSP Settings](https://android.googlesource.com/platform/packages/apps/Settings/+/refs/heads/main/)\n\n## Usage\n\nThis library is designed with both extensibility and ease-of-use in mind.\n\nBasic usage of this library involves invoking the `ProvidePreferenceLocals` composable, and then calling the `*Preference` helper functions in a `LazyColumn` composable:\n\n```kotlin\nAppTheme {\n    ProvidePreferenceLocals {\n        // Other composables wrapping the LazyColumn ...\n        LazyColumn(modifier = Modifier.fillMaxSize()) {\n            switchPreference(\n                key = \"switch_preference\",\n                defaultValue = false,\n                title = { Text(text = \"Switch preference\") },\n                icon = { Icon(imageVector = Icons.Outlined.Info, contentDescription = null) },\n                summary = { Text(text = if (it) \"On\" else \"Off\") }\n            )\n        }\n    }\n}\n```\n\n### Preferences\n\nBuilt-in types of preferences include:\n\n- [`Preference`](library/src/main/java/me/zhanghai/compose/preference/Preference.kt)\n- [`PreferenceCategory`](library/src/main/java/me/zhanghai/compose/preference/PreferenceCategory.kt)\n- [`CheckboxPreference`](library/src/main/java/me/zhanghai/compose/preference/CheckboxPreference.kt)\n- [`FooterPreference`](library/src/main/java/me/zhanghai/compose/preference/FooterPreference.kt)\n- [`ListPreference`](library/src/main/java/me/zhanghai/compose/preference/ListPreference.kt) (supports both alert dialog and dropdown menu)\n- [`MultiSelectListPreference`](library/src/main/java/me/zhanghai/compose/preference/MultiSelectListPreference.kt)\n- [`RadioButtonPreference`](library/src/main/java/me/zhanghai/compose/preference/RadioButtonPreference.kt)\n- [`SliderPreference`](library/src/main/java/me/zhanghai/compose/preference/SliderPreference.kt)\n- [`SwitchPreference`](library/src/main/java/me/zhanghai/compose/preference/SwitchPreference.kt)\n- [`TextFieldPreference`](library/src/main/java/me/zhanghai/compose/preference/TextFieldPreference.kt)\n- [`TwoTargetIconButtonPreference`](library/src/main/java/me/zhanghai/compose/preference/TwoTargetIconButtonPreference.kt)\n- [`TwoTargetSwitchPreference`](library/src/main/java/me/zhanghai/compose/preference/TwoTargetSwitchPreference.kt)\n\nEach type of built-in preference includes 3 kinds of APIs:\n\n1. A `LazyListScope.*Preference` extension function, which is the easiest way to use preferences in this library, and helps developers to avoid boilerplates like having to specify the key twice for the `LazyColumn` and the `Preference`.\n2. A `*Preference` composable that takes a `MutableState`, which allows developers to bring in any kind of state they currently have.\n3. A `*Preference` composable that takes `value` and `onValueChange`, which allows developers to use the preference without a state and even in non-preference scenarios.\n\n### Theming\n\nThe visual appearance of the preferences can be customized by providing a custom [`PreferenceTheme`](library/src/main/java/me/zhanghai/compose/preference/PreferenceTheme.kt) with `preferenceTheme` to `ProvidePreferenceLocals` or `ProvidePreferenceTheme`.\n\nCustomizable values in the theme include most dimensions, colors and text styles used by the built-in preferences.\n\n### Data source\n\nThe data source of the preferences can be customized by providing a custom `MutableStateFlow\u003cPreferences\u003e` to `ProvidePreferenceLocals` or `ProvidePreferenceFlow`.\n\nThe [`Preferences`](library/src/main/java/me/zhanghai/compose/preference/Preferences.kt) interface defined in this library is similar to the AndroidX DataStore [`Preferences`](https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences) class, but:\n\n- It can be implemented by other mechanisms like [`SharedPreferences`](https://developer.android.com/reference/android/content/SharedPreferences), thanks to being a public interface instead of an abstract class with only an internal constructor.\n- It doesn't have to be produced and updated via a [`DataStore`](https://developer.android.com/reference/kotlin/androidx/datastore/core/DataStore).\n- It doesn't mandate a fixed set of types that an implementation has to support, so that implementations have the flexibility to support much more or less types. The implementations within this library will always support the types supported by `SharedPreferences` (the same as AndroidX DataStore).\n\nThe default data source provided by this library (`defaultPreferenceFlow`) is implemented with `SharedPreferences`, because:\n\n- `SharedPreferences` is available as part of the Android framework, and doesn't require external dependencies like AndroidX DataStore which [bundles its own copy of `protobuf-lite`](https://cs.android.com/androidx/platform/frameworks/support/+/androidx-main:datastore/datastore-preferences-core/build.gradle;l=108;drc=9fd0cda7bb963d41fd25645b0761776caa830ed7).\n- `SharedPreferences` can actually be [10x faster](https://stackoverflow.com/q/71601343) than AndroidX DataStore, likely due to its existing optimizations and simple threading and persistence model (XML is simple enough to be faster than Protobuf).\n- `SharedPreferences` has a synchronous API, but it is actually async except for the first (un-cached) read, and allows in-memory value change without waiting for the disk write to complete, which is good for the preference use case.\n- Existing users of `SharedPreferences` can use this library directly with the default data source.\n\nThere should only be at most one instance of `defaultPreferenceFlow`, similar to `DataStore` in AndroidX DataStore. It is also only for usage within a single process due to being backed by `SharedPreferences`.\n\nIf AndroidX DataStore is considered more appropriate for your use case, e.g. you are working on a [Compose Multiplatform](https://www.jetbrains.com/lp/compose-multiplatform/) project or you need multi-process support, you can also easily use a AndroidX DataStore backed implementation that provides a `MutableStateFlow\u003cPreferences\u003e`.\n\n## License\n\n    Copyright 2023 Google LLC\n\n    Licensed under the Apache License, Version 2.0 (the \"License\");\n    you may not use this file except in compliance with the License.\n    You may obtain a copy of the License at\n\n        https://www.apache.org/licenses/LICENSE-2.0\n\n    Unless required by applicable law or agreed to in writing, software\n    distributed under the License is distributed on an \"AS IS\" BASIS,\n    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n    See the License for the specific language governing permissions and\n    limitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzhanghai%2Fcomposepreference","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzhanghai%2Fcomposepreference","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzhanghai%2Fcomposepreference/lists"}