ComposePrefs

ComposePrefs is a preferences library for Jetpack Compose which makes it easy to implement preferences/settings in your Compose Android app. Preferences are created and positioned using an intuitive and easy to use API which follows a similar design to the existing Material Composables. Currently, the library uses the Composables available from M2 as M3 is not quite stable enough to use. ComposePrefs uses DataStore to store the actual preference data.

This repository provides a sample application in which creation and use of each preference composable is demonstrated. The main settings screen can be found here.

Currently supported preference composables

• TextPref: Basic preference which only displays text and can be clicked on.
• CheckBoxPref: Preference with a trailing CheckBox which can be (un)checked.
• SwitchPref: Preference with a trailing Switch which can be (un)checked.
• EditTextPref: Preference which opens a TextField in a dialog for textual user input.
• SliderPref: Preference which displays a Slider to allow for inline numerical user input.
• DropDownPref: Preference which shows entries in a dropdown menu and allows for user selection.
• ListPref: Preference which opens a list of items in a dialog from which the user can select a single entry.
• MultiSelectListPref: Preference which opens a list of items in a dialog from which the user can select multiple entries at once.

There is also support for Groups/Categories which can be created using the prefsGroup function. Usage is shown below.

Usage

First create a DataStore, for example in your MainActivity.kt:

val Context.dataStore: DataStore<Preferences> by preferencesDataStore(name = "settings")

Next in your actual Preferences/Settings screen, you can create a PrefScreen and pass in your DataStore as you would any other Composable:

PrefsScreen(dataStore = LocalContext.current.dataStore) {
    ..
}

Within the PrefsScreen, you can add individual preference items using prefsItem or add a group with prefsGroup:

prefsItem { TextPref(title = "Just some text", summary = "Here is some summary text") }


prefsGroup("CheckBoxPref") {
    prefsItem { CheckBoxPref(key = "cb1", title = "Simple checkbox 1") }
    prefsItem { TextPref(title = "Just some text", summary = "Here is some summary text") }
    prefsItem { SwitchPref(key = "sw1", title = "Simple switch 1") }
}

Composables

Each composable excluding TextPref has a mandatory key parameter. This is the key 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 behaviour.

TextPref

TextPref(title = "Just some text", summary = "But now with a summary")

CheckBoxPref

CheckBoxPref(
    key = "cb1",
    title = "Simple checkbox",
    summary = "But with a leading icon and summary",
    leadingIcon = { Icon(Icons.Filled.Person, "Person") }
)

SwitchPref

SwitchPref(
    key = "sw4",
    title = "Simple switch",
    summary = "But with a leading icon and summary",
    leadingIcon = { Icon(Icons.Filled.Home, "Home") }
)

EditTextPref

EditTextPref(
    key = "et1",
    title = "EditText example",
    summary = "But it has a dialog title and message",
    dialogTitle = "Dialog Title",
    dialogMessage = "Dialog Message"
)

SliderPref

SliderPref(
    key = "sp1",
    title = "Slider example with custom range and value shown on side",
    valueRange = 50f..200f,
    showValue = true
)

DropDownPref

DropDownPref(
    key = "dd1",
    title = "Dropdown with currently selected item as summary",
    useSelectedAsSummary = true,
    entries = mapOf(
        "0" to "Entry 1",
        "1" to "Entry 2",
        "2" to "Entry 3"
    )
)

ListPref

ListPref(
    key = "l1",
    title = "ListPref example",
    summary = "Opens up a dialog of options",
    entries = mapOf(
        "0" to "Entry 1",
        "1" to "Entry 2",
        "2" to "Entry 3",
        "3" to "Entry 4",
        "4" to "Entry 5"
    )
)

MultiSelectListPref

MultiSelectListPref(
    key = "msl1",
    title = "MultiSelectListPref",
    summary = "Pick multiple entries at once",
    entries = mapOf(
        "0" to "Entry 1",
        "1" to "Entry 2",
        "2" to "Entry 3",
        "3" to "Entry 4",
        "4" to "Entry 5"
    )
)

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. After all, this is still version 1.0.0 and there are bound to be bugs and missing features.

Screenshots of this sample app

Download

In your settings.gradle file add the following

maven { url "https://jitpack.io" }

and in your module build.gradle file add the dependencies

implementation "com.github.JamalMulla:ComposePrefs:<version>" // Current is 1.0.0
implementation "androidx.datastore:datastore-preferences:1.0.0"