Compose Preference

Each built-in preference type offers four ways to be used, depending on your state management needs:

1. LazyListScope.*Preference (Key-based): The easiest way for LazyColumn. You provide a key and defaultValue, and the library handles the rest.
2. LazyListScope.*Preference (State-based): An overload for LazyColumn that accepts an explicit value and onValueChange callback.
3. *Preference Composable (MutableState): A standalone composable that takes a MutableState, useful for integrating with existing state objects.
4. *Preference Composable (Value/Callback): A standalone composable that takes value and onValueChange, useful for stateless or non-preference scenarios.

The data source is managed by providing a MutableStateFlow<Preferences> to ProvidePreferenceLocals or ProvidePreferenceFlow.

By default, the library uses createDefaultPreferenceFlow(), which uses:

• SharedPreferences on Android
• NSUserDefaults on Apple
• Preferences on JVM
• localStorage on Web

Important: There should be at most one invocation of createDefaultPreferenceFlow() in your application, and it is intended for single-process usage. If you require multi-process support, you should implement your own MutableStateFlow<Preferences> backed by AndroidX DataStore.

To use the library, wrap your preference UI with ProvidePreferenceLocals. You can then use various *Preference extension functions directly inside a LazyColumn to build your settings screen. This approach automatically handles key management and reduces boilerplate.

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

Add the following dependency to your build.gradle file to use Compose Preference in your project:

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

The library provides several built-in preference types for common settings tasks:

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

By default, the library's Preferences implementation supports most types except Long to ensure cross-platform compatibility. You can opt-in to Long support for specific platforms:

• Android: Set isDefaultPreferenceFlowAndroidLongSupportEnabled to true to enable Long support.
• Apple: Set isDefaultPreferenceFlowAppleLongOnlySupportEnabled to true to use Long in place of Int.