Implements preference management for UI settings with a focus on customization and scalability. Supports serialization, custom color schemes, typography, and spacing, enhancing user interface design adaptability.
Surfaced from shared tags and platforms — no rankings paid for.
Preference Kotlin Multiplatform Project implementation for Jetpack Compose Material 3.
This is not an officially supported Google product.
build.gradle
implementation 'io.github.strabled:ComposePreferences:${latest-version}'
build.gradle.kts
implementation('io.github.strabled:ComposePreferences:${latest-version}')
//or with verion catalog
implementation(libs.compose.preferences)
[versions]
composePreferences = { latest-version }
[libraries]
compose-preferences = { group = "io.github.strabled", name = "ComposePreferences", version.ref = "composePreferences" }
First you set up your DataStore by using the ProvideDataStoreManager method outside your Preferencs/Setting screen and set the preferences by using the PreferenceBuilder.
The PreferenceBuilder can be obtained by using the buildPreferences methode. The PreferenceBuilder is then passed to the setPreferences methode:
ProvideDataStoreManager {
val preferences = buildPreferences(LocalDataStoreManager.current) {
"sl1" defaultValue false
"cp1" defaultValue (Color.Blue serializeWith colorSerializer)
..
}
setPreferences(preferences)
SettingsScreen()
}
The buildPreferences context can also be used directly in the setPreferences methode. Or a lambda with a PreferenceBuilder receiver can be passed:
val preferences: PreferenceBuilder.() -> Unit = {
"sl1" defaultValue false
"cp1" defaultValue (Color.Blue serializeWith colorSerializer)
..
}
ProvideDataStoreManager {
setPreferences(preferences)
..
}
You can provide your own DataStoreManager to the ProvideDataStoreManager if you don't want to use the default one. For Android, this can be done like this:
val Context.dataStore by preferencesDataStore(name = "settings")
val dataStoreManager = DataStoreManager(context = LocalContext.current, dataStore = LocalContext.current.dataStore)
ProvideDataStoreManager(dataStoreManager = dataStoreManager) {
..
}
Next in your actual Preferences/Settings screen, you can create a PreferenceScreen:
PreferenceScreen() {
..
}
Here you can define the Scaffhold components such as a Top Bar, Floating Action Button, ... of your PreferenceScreen:
PreferenceScreen(scaffoldComponents = ScaffholdComponents(topBar = { SettingsTopBar() })) {
..
}
Within the PreferenceScreen, you can add individual preference items using preferenceItem, add a category (group) of items with preferenceCategory and a footer with
preferenceFooter:
preferenceItem { TextPreference(title = "Only some text") }
preferenceCategory("Text Preference") {
preferenceItem { TextPreference(title = "Only some text") }
preferenceItem { SliderPreference(preference = getPreference<Float>("sl1"), title = "Simple slider", showValue = true) }
preferenceItem { CheckBoxPreference(preferences = getPreference<Boolean>("cb1"), title = "Simple checkbox") }
}
preferenceFooter(
title = "Settings Example",
subtitle = { Text(text = "Version 1.0.0") },
icon = { Icon(Icons.Outlined.Info, ) }
)
If you want to change the appearance of the PreferenceScreen and the used composables in there, you can give the PreferenceScreen a custom PreferenceColorScheme,
PreferenceTypography and PreferenceSpacing.
If you only want to change certain values and use the default values for the rest, you can use the lightPreferenceColorTheme, darkPreferenceColorTheme,
preferenceTypography and preferenceSpacing.
This is the preferable approach to not completly destroy the layout of the PreferenceScreen -- and it's less work for you ;)
val darkTheme = darkPreferenceColorTheme(categoryHeaderColor = MaterialTheme.colorScheme.secondary)
val lightTheme = lightPreferenceColorTheme(categoryHeaderColor = MaterialTheme.colorScheme.secondary)
val typography = preferenceTypography(summaryStyle = MaterialTheme.typography.bodySmall)
val spacing = preferenceSpacing(dialogContentGap = 16.dp)
PreferenceScreen(
theme = if (isSystemInDarkTheme()) darkTheme else lightTheme,
typography = typography,
spacing = spacing
) {
..
}
If you want to use the Preferences outside a fullsize componenet, you can use the PreferenceContainer:
PreferenceContainer {
..
}
To get the preference, you can use the convinience function getPreference inside ProvideDataStoreManager which retrieves the preference from the DataStoreManager by the given
key.
A StateFlow of the value of the preference can be obtained by delegating the preference to a variable, and it can be set with the Preference.set method.
val preference: Preference<Int> = getPreference<Int>("intKey")
val preferenceData: StateFlow<Int> by preference
val preferenceValue: Int by preferenceData.collectAsState()
The preferences support serialization with the kotlin serialization plugin.
@Serializable
data class User(val name: String, val age: Int)
val preferenceData: StateFlow<User> by getPreference("userKey")
Each preference composable excluding TextPref has a mandatory preference parameter. This preference has the key name that will be used in the DataStore and is
equivalent to the key used in previous Android preference libraries.
You should be using unique keys for each preference. Using the same key for different preferences of the same type will result in their values being the same. Using the same key for different preferences of different types may result in unexpected behavior.
TextPreference(
title = "Only some text",
summary = {
Text(text = "Now we have a summary")
}
)
SwitchPreference(
preference = getPreference("sw4"),
title = "Simple switch",
summary = { Text(text = "Now with a leading icon") },
leadingIcon = { Icon(Icons.Default.Lock, "Lock") }
)
SliderPreference(
preference = getPreference<Int>("sl2"),
title = "Simple slider",
steps = 9,
valueRange = 0f..10f,
showValue = true
)
CheckBoxPreference(
preference = getPreference<Boolean>("cb4"),
title = "Simple checkbox",
summary = { Text(text = "Now with a leading icon") },
leadingIcon = { Icon(Icons.Default.Lock, "Lock") }
)
EditTextPreference(
preference = getPreference<String>("et6"),
title = "Simple edit text",
summary = { Text(text = "Now with a custom dialog title and message") },
dialogText = DialogText("Custom title", "We have a custom message here")
)
DialogListPreference(
preference = getPreference<String>("dl1"),
title = "Simple select list",
items = mapOf("item1" to "Item 1", "item2" to "Item 2"),
summary = { Text(text = "Opens a dialog to select from a list of items") }
)
DropDownListPreference(
preference = getPreference<String>("dl1"),
title = "Simple drop down list",
items = mapOf("item1" to "Item 1", "item2" to "Item 2"),
summary = { Text(text = "Opens a dialog to select from a list of items") }
)
BottomSheetListPreference(
preference = getPreference<String>("bl1"),
title = "Simple bottom sheet list",
items = mapOf("item1" to "Item 1", "item2" to "Item 2"),
summary = { Text(text = "Opens a bottom sheet to select from a list of items") }
)
MultiSelectPreference(
preference = getPreference<Set<String>>("msl1"),
title = "Simple multi select list",
items = mapOf("0" to "Item 1", "10" to "Item 2", "20" to "Item 3", "30" to "Item 4", "40" to "Item 5"),
summary = { Text(text = "Opens a dialog for selecting multiple items from a list of items") }
)
ColorPickerPreference(
preference = getPreference("cp1"),
title = "Simple color picker",
summary = { Text(text = "A color picker dialog") }
)
And that's it! You can create your whole preference screen in this way, and you can modify the individual parameters of each preference composable to achieve the functionality you require. If something is missing, please create an Issue so we can discuss possible solutions.
You can help this project by contributing to it. If you have a feature request or have found a bug, feel free to share this by following the CONTRIBUTING.md guidelines. Any help is appreciated!