Compose Preference

https://github.com/zhanghai/composepreference
Admin
A preference implementation for Jetpack Compose Material 3, providing various customizable UI...
Tokens:2,534
Snippets:14
Trust Score:8.1
License:Apache-2.0
Update:1 year ago
Show doc for...
Tokens:
Raw
### Basic SwitchPreference Usage in Jetpack Compose

Source: https://github.com/zhanghai/composepreference/blob/master/README.md

This example demonstrates the basic usage of a SwitchPreference within a Jetpack Compose application. It requires wrapping the preferences with `ProvidePreferenceLocals` and placing them inside a `LazyColumn`. The `switchPreference` helper function simplifies the setup, automatically handling key management.

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

--------------------------------

### Basic Setup - ProvidePreferenceLocals in Kotlin

Source: https://context7.com/zhanghai/composepreference/llms.txt

Initializes the preference system with a data source and theme, providing context for all preference composables within its scope. It requires Jetpack Compose dependencies and the compose-preference library. The function accepts optional flow and theme parameters.

```kotlin
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import me.zhanghai.compose.preference.*

@Composable
fun SettingsScreen() {
    AppTheme {
        ProvidePreferenceLocals(
            flow = createDefaultPreferenceFlow(), // Optional: defaults to SharedPreferences
            theme = preferenceTheme() // Optional: customize appearance
        ) {
            LazyColumn(modifier = Modifier.fillMaxSize()) {
                // Add preferences here
            }
        }
    }
}
```

--------------------------------

### Slider Preference in Kotlin

Source: https://context7.com/zhanghai/composepreference/llms.txt

Provides a preference with a slider for selecting numeric values. Supports continuous or stepped sliders within a defined range. The slider's current value is displayed to the user, formatted as a percentage in this example.

```kotlin
import kotlin.math.roundToInt

LazyColumn {
    sliderPreference(
        key = "volume",
        defaultValue = 0.5f,
        title = { Text(text = "Volume") },
        valueRange = 0f..1f,
        valueSteps = 9, // Creates 10 discrete steps
        summary = { value -> Text(text = "Adjust audio volume") },
        valueText = { value ->
            Text(text = "${(value * 100).roundToInt()}%")
        }
    )
}
```

--------------------------------

### Integrate AndroidX DataStore with Compose Preference

Source: https://context7.com/zhanghai/composepreference/llms.txt

This Kotlin code demonstrates integrating AndroidX DataStore as a custom preferences backend for Compose Preference. It includes an adapter class `DataStorePreferencesAdapter` to bridge DataStore's `Preferences` with the `Preferences` interface expected by Compose Preference. The `DataStoreBackedPreferences` composable shows how to provide this custom data source using `ProvidePreferenceLocals`.

```kotlin
import kotlinx.coroutines.flow.MutableStateFlow
import me.zhanghai.compose.preference.*

class DataStorePreferencesAdapter(
    private val preferences: androidx.datastore.preferences.core.Preferences
) : Preferences {
    override fun <T> get(key: String): T? {
        // Implement custom retrieval logic
        return preferences[androidx.datastore.preferences.core.stringPreferencesKey(key)] as? T
    }

    override fun asMap(): Map<String, Any> {
        return preferences.asMap().mapKeys { it.key.name }
    }

    override fun toMutablePreferences(): MutablePreferences {
        return MutableMapPreferences(asMap().toMutableMap())
    }
}

@Composable
fun DataStoreBackedPreferences() {
    val dataStoreFlow: MutableStateFlow<Preferences> = // Create from DataStore

    ProvidePreferenceLocals(flow = dataStoreFlow) {
        LazyColumn {
            switchPreference(
                key = "setting",
                defaultValue = false,
                title = { Text("DataStore-backed setting") }
            )
        }
    }
}
```

--------------------------------

### Custom Theme Configuration for Preferences in Kotlin

Source: https://context7.com/zhanghai/composepreference/llms.txt

Demonstrates how to customize the appearance of all preferences within a composable scope by providing a custom `PreferenceTheme`. This allows control over padding, spacing, colors, and typography.

```kotlin
import androidx.compose.material3.MaterialTheme
import androidx.compose.ui.unit.dp

@Composable
fun CustomThemedSettings() {
    val customTheme = preferenceTheme(
        padding = PaddingValues(horizontal = 20.dp, vertical = 12.dp),
        horizontalSpacing = 20.dp,
        iconColor = MaterialTheme.colorScheme.primary,
        titleColor = MaterialTheme.colorScheme.onSurface,
        titleTextStyle = MaterialTheme.typography.titleMedium,
        summaryColor = MaterialTheme.colorScheme.onSurfaceVariant,
        disabledOpacity = 0.5f
    )

    ProvidePreferenceLocals(theme = customTheme) {
        LazyColumn {
            switchPreference(
                key = "example",
                defaultValue = false,
                title = { Text("Custom styled preference") }
            )
        }
    }
}
```

--------------------------------

### Direct State Management for Preferences in Kotlin

Source: https://context7.com/zhanghai/composepreference/llms.txt

Shows how to use `MutableState` directly to manage preference state without relying on persistent storage. This is useful for temporary states or when integrating with existing state management solutions.

```kotlin
import androidx.compose.runtime.*
import me.zhanghai.compose.preference.SwitchPreference

@Composable
fun ManualStateExample() {
    val darkModeState = remember { mutableStateOf(false) }

    // Apply theme change immediately
    LaunchedEffect(darkModeState.value) {
        applyTheme(darkModeState.value)
    }

    SwitchPreference(
        state = darkModeState,
        title = { Text("Dark mode") },
        summary = { Text(if (darkModeState.value) "On" else "Off") }
    )
}
```

--------------------------------

### Gradle Dependency for Compose Preference

Source: https://github.com/zhanghai/composepreference/blob/master/README.md

This snippet shows how to add the Compose Preference library as a dependency in your Android project using Gradle. Ensure you use the latest version compatible with your project.

```kotlin
implementation("me.zhanghai.compose.preference:preference:2.1.0")
```

--------------------------------

### Switch Preference in Kotlin

Source: https://context7.com/zhanghai/composepreference/llms.txt

Implements a toggleable preference with a switch widget for boolean settings. It uses a LazyColumn scope and requires basic Compose UI and compose-preference imports. The `switchPreference` composable takes a key, default value, title, optional modifier, icon, summary, and an enabled state.

```kotlin
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.outlined.Notifications
import androidx.compose.material3.Icon
import androidx.compose.material3.Text
import androidx.compose.ui.Modifier
import me.zhanghai.compose.preference.*

LazyColumn {
    switchPreference(
        key = "notifications_enabled",
        defaultValue = true,
        title = { enabled -> Text(text = "Notifications") },
        modifier = Modifier.fillMaxWidth(),
        icon = { Icon(imageVector = Icons.Outlined.Notifications, contentDescription = null) },
        summary = { enabled -> Text(text = if (enabled) "Enabled" else "Disabled") },
        enabled = { true } // Optional: make preference interactable
    )
}
```

--------------------------------

### Simple Clickable Preference in Kotlin

Source: https://context7.com/zhanghai/composepreference/llms.txt

A fundamental preference item that is clickable but does not display an input widget. It's commonly used for navigation actions or triggering events, and can optionally display an icon and summary text.

```kotlin
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.outlined.Info

LazyColumn {
    preference(
        key = "about",
        title = { Text(text = "About") },
        summary = { Text(text = "Version 1.0.0") },
        icon = { Icon(imageVector = Icons.Outlined.Info, contentDescription = null) },
        onClick = { /* Navigate to about screen */ }
    )
}
```

--------------------------------

### List Preference (Dropdown Menu) in Kotlin

Source: https://context7.com/zhanghai/composepreference/llms.txt

Creates a single-selection list preference displayed as a dropdown menu for a more compact UI. This composable is used within a LazyColumn and requires compose-preference. It takes a key, default value, list of values, title, summary, and the type set to DROPDOWN_MENU.

```kotlin
LazyColumn {
    listPreference(
        key = "language",
        defaultValue = "en",
        values = listOf("en", "es", "fr", "de"),
        title = { Text(text = "Language") },
        summary = { lang -> Text(text = lang.uppercase()) },
        type = ListPreferenceType.DROPDOWN_MENU
    )
}
```

--------------------------------

### Multi-Select List Preference in Kotlin

Source: https://context7.com/zhanghai/composepreference/llms.txt

Implements a preference that allows users to select multiple items from a list displayed in an alert dialog with checkboxes. It uses LazyColumn for efficient rendering and defines default selections, available values, and text representations for selected items.

```kotlin
LazyColumn {
    multiSelectListPreference(
        key = "notification_categories",
        defaultValue = setOf("messages", "updates"),
        values = listOf("messages", "updates", "promotions", "social"),
        title = { Text(text = "Notification categories") },
        summary = { selected ->
            Text(text = if (selected.isEmpty()) "None selected" else selected.sorted().joinToString(", "))
        },
        valueToText = { category ->
            androidx.compose.ui.text.AnnotatedString(category.replaceFirstChar { it.uppercase() })
        }
    )
}
```

--------------------------------

### List Preference (Alert Dialog) in Kotlin

Source: https://context7.com/zhanghai/composepreference/llms.txt

Implements a single-selection list preference presented as an alert dialog with radio buttons. It's used within a LazyColumn and requires compose-preference. Key parameters include a key, default value, a list of selectable values, title, summary, type (ALERT_DIALOG), and a value-to-text conversion lambda.

```kotlin
LazyColumn {
    listPreference(
        key = "theme_preference",
        defaultValue = "system",
        values = listOf("light", "dark", "system"),
        title = { Text(text = "Theme") },
        summary = { value ->
            val displayName = when (value) {
                "light" -> "Light"
                "dark" -> "Dark"
                "system" -> "System default"
                else -> value
            }
            Text(text = displayName)
        },
        type = ListPreferenceType.ALERT_DIALOG,
        valueToText = {
            androidx.compose.ui.text.AnnotatedString(
                when (value) {
                    "light" -> "Light"
                    "dark" -> "Dark"
                    "system" -> "System default"
                    else -> value
                }
            )
        }
    )
}
```

--------------------------------

### Text Field Preference in Kotlin

Source: https://context7.com/zhanghai/composepreference/llms.txt

A preference that opens a dialog containing a text input field. Users can enter string values, with options to transform the input text into a value and vice-versa. It handles empty input states for the summary.

```kotlin
LazyColumn {
    textFieldPreference(
        key = "username",
        defaultValue = "",
        title = { Text(text = "Username") },
        textToValue = { text -> text.takeIf { it.isNotBlank() } },
        summary = { value -> Text(text = value.ifEmpty { "Not set" }) },
        valueToText = { it }
    )
}
```

--------------------------------

### Checkbox Preference in Kotlin

Source: https://context7.com/zhanghai/composepreference/llms.txt

Provides a toggleable preference with a checkbox widget, offering an alternative to the switch preference. This composable is used within a LazyColumn and requires compose-preference. It accepts a key, default value, title, and an optional summary lambda.

```kotlin
LazyColumn {
    checkboxPreference(
        key = "auto_backup",
        defaultValue = false,
        title = { Text(text = "Automatic backup") },
        summary = { checked -> Text(text = if (checked) "Back up daily" else "Manual backup only") }
    )
}
```
Tokens:
Raw