zhanghai/ComposePreference

Compose Preference

Preference implementation for Jetpack Compose Material 3.

This is not an officially supported Google product.

Preview

Integration

Gradle:

implementation("me.zhanghai.compose.preference:preference:2.2.0")

Design

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:

• Material Design 3
• Material Design 2 Android Settings
• Android settings design guidelines
• AndroidX Preference
• AOSP Settings

Usage

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") }
            )
        }
    }
}

Preferences

Built-in types of preferences include:

• Preference
• PreferenceCategory
• CheckboxPreference
• FooterPreference
• ListPreference (supports both alert dialog and dropdown menu)
• MultiSelectListPreference
• RadioButtonPreference
• SliderPreference
• SwitchPreference
• TextFieldPreference
• TwoTargetIconButtonPreference
• TwoTargetSwitchPreference

Each type of built-in preference includes 4 kinds of APIs:

1. 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.
2. A LazyListScope.*Preference extension function, which is an overload of the first extension function but accepts value and onValueChange instead.
3. A *Preference composable that takes a MutableState, which allows developers to bring in any kind of state they currently have.
4. A *Preference composable that takes value and onValueChange, which allows developers to use the preference without a state and even in non-preference scenarios.

Theming

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.

Data source

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:

• It can be implemented by other mechanisms like SharedPreferences, thanks to being a public interface instead of an abstract class with only an internal constructor.
• It doesn't have to be produced and updated via a DataStore.
• 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 supports most of the types supported by 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.

The default data source provided by this library (createDefaultPreferenceFlow()) is implemented with SharedPreferences on Android (or NSUserDefaults on Apple, Preferences on JVM, and localStorage on Web), because:

• 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.
• 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.
• Existing users of SharedPreferences can use this library directly with the default data source.
• AndroidX DataStore doesn't support Kotlin/JS and Kotlin/Wasm yet.

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.

License

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://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.