Implements a preference system with Material 3 design for Jetpack Compose, offering various preference types, theming options, and customizable data sources for flexible and efficient UI development.
Preference implementation for Jetpack Compose Material 3.
This is not an officially supported Google product.
Gradle:
implementation("me.zhanghai.compose.preference:preference:2.2.0")
There 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:
This library is designed with both extensibility and ease-of-use in mind.
Basic usage of this library involves invoking the ProvidePreferenceLocals composable, and then calling the *Preference helper functions in a LazyColumn composable:
AppTheme {
ProvidePreferenceLocals {
// Other composables wrapping the LazyColumn ...
LazyColumn(modifier = Modifier.fillMaxSize()) {
switchPreference(
key = "switch_preference",
defaultValue = false,
title = { Text(text = "Switch preference") },
icon = { Icon(imageVector = Icons.Outlined.Info, contentDescription = null) },
summary = { Text(text = if (it) "On" else "Off") }
)
}
}
}
Built-in types of preferences include:
Each type of built-in preference includes 4 kinds of APIs:
The visual appearance of the preferences can be customized by providing a custom PreferenceTheme with preferenceTheme to ProvidePreferenceLocals or ProvidePreferenceTheme.
Customizable values in the theme include most dimensions, colors and text styles used by the built-in preferences.
The data source of the preferences can be customized by providing a custom MutableStateFlow<Preferences> to ProvidePreferenceLocals or ProvidePreferenceFlow.
The Preferences interface defined in this library is similar to the AndroidX DataStore Preferences class, but:
The default data source provided by this library (createDefaultPreferenceFlow()) is implemented with SharedPreferences on Android (or NSUserDefaults on Apple, on JVM, and on Web), because:
There should only be at most one invocation of createDefaultPreferenceFlow(), similar to creating DataStore in AndroidX DataStore. It is also only for usage within a single process due to being backed by SharedPreferences.
If AndroidX DataStore is considered more appropriate for your use case, e.g. you need multi-process support, you can also create an AndroidX DataStore backed implementation that provides a MutableStateFlow<Preferences> on your own.
Copyright 2023 Google LLC
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
https:
Unless applicable law agreed to writing, software
distributed under the License distributed an BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express implied.
See the License the specific language governing permissions
limitations under the License.
ListPreference (supports both alert dialog and dropdown menu)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.LazyListScope.*Preference extension function, which is an overload of the first extension function but accepts value and onValueChange instead.*Preference composable that takes a MutableState, which allows developers to bring in any kind of state they currently have.*Preference composable that takes value and onValueChange, which allows developers to use the preference without a state and even in non-preference scenarios.SharedPreferences, thanks to being a public interface instead of an abstract class with only an internal constructor.DataStore.SharedPreferences except for Long by default (due to non-Android platforms). You can opt in to Android-only support for Long by setting isDefaultPreferenceFlowAndroidLongSupportEnabled to true, and you can opt in to Apple-only support for Long in place of Int by setting isDefaultPreferenceFlowAppleLongOnlySupportEnabled to true.PreferencesSharedPreferences 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.SharedPreferences can actually be 10x faster than AndroidX DataStore, likely due to its existing optimizations and simple threading and persistence model (XML is simple enough to be faster than Protobuf).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.SharedPreferences can use this library directly with the default data source.Surfaced from shared tags and platforms — no rankings paid for.