Store Preferences with DataStore

Room is perfect for lists of things: items, expenses, bus stops. But much of what an app remembers is small and simple: "dark theme on", "show items as a grid", "last search was lagos", "the user has finished the tutorial". Creating a database table for a single true/false value would be overkill.

Jetpack DataStore is the modern way to save small key-value settings. It is asynchronous, built on coroutines and Flow, safe to use from any thread, and replaces the old SharedPreferences. In this lesson you will add a persistent layout toggle to an app, understand why DataStore is built the way it is, and plan the unit's capstone: the Flight Search project, which combines Room (the airports) and DataStore (the user's last search).

This lesson covers the four items of Pathway 3, Unit 6 of the official Android Basics with Compose course: Introduction to DataStore, Preferences DataStore, Save preferences locally with DataStore and Project: Create a flight search app.

By the end you will be able to:

• Choose among DataStore, Room, SharedPreferences and plain files.
• Add the Preferences DataStore dependency and create a single DataStore instance.
• Define typed keys, read preferences as a Flow, and write them with edit { }.
• Handle IOException when reading.
• Build the repository, ViewModel and Compose UI that save and restore a layout choice.
• Explain Proto DataStore and when it matters.
• Plan the Flight Search project.

Big idea: a preference is a small fact that must outlive the app process. DataStore stores it, exposes it as a Flow, and your UI simply collects.

• Flow, map, catch and stateIn (lesson 33).
• Repositories and the app container (lesson 30).
• ViewModel and UI state (lessons 24 and 25).
• Room basics (lesson 34), used by the project at the end.
• Coroutines (lesson 28). DataStore writes are suspend functions.

A rule of thumb: if you would be happy to store it in a Map<String, Any>, use DataStore. If you want to ask questions like "all items where...", use Room.

DataStore is not for secrets such as passwords or tokens: its files are plain data in your app's private folder, protected by the operating system's sandbox, not encrypted by DataStore. Use the platform's encrypted storage and keystore facilities for secrets.

Why DataStore beats SharedPreferences

Older code uses SharedPreferences. You will meet it in existing projects, so know its problems:

• Reads are synchronous. A first read can touch the disk on the main thread and cause jank.
• It offers no way to report errors from reading or parsing the file.
• Writes with apply() are fire-and-forget, so you cannot tell when they finished or whether they failed.
• It has no built-in way to observe changes as a stream of values.

DataStore fixes each of these with coroutines and Flow. It also writes transactionally: an edit { } block either fully succeeds or leaves the data unchanged.

UI  --event-->  ViewModel  --suspend-->  Repository  --edit{}-->  DataStore (file on disk)
UI  <--state--  ViewModel  <---Flow----  Repository  <--data----  DataStore

Look up the current stable version of datastore-preferences on the release page (https://developer.android.com/jetpack/androidx/releases/datastore) and add it to the version catalog:

[versions]
datastore = "<latest stable>"
[libraries]
androidx-datastore-preferences = { group = "androidx.datastore", name = "datastore-preferences", version.ref = "datastore" }

dependencies {
 implementation(libs.androidx.datastore.preferences)
}

Sync. The official codelab used a direct dependency string (androidx.datastore:datastore-preferences:<version>) in the module file; the version catalog does the same job in one place.

We will add a persistent list or grid layout toggle to a small catalogue app (such as the Affirmations app of lesson 21, or Dessert Release in the official codelab). The preference is a single boolean: isLinearLayout.

Create exactly one DataStore

// InventoryApplication.kt or a top-level file
import android.content.Context
import androidx.datastore.core.DataStore
import androidx.datastore.preferences.core.Preferences
import androidx.datastore.preferences.preferencesDataStore
private const val LAYOUT_PREFERENCE_NAME = "layout_preferences"
val Context.dataStore: DataStore<Preferences> by preferencesDataStore(
 name = LAYOUT_PREFERENCE_NAME
)

This property delegate creates the DataStore the first time it is used and returns the same instance afterwards. Two rules matter:

1. Declare it once, at the top level of a Kotlin file, never inside a class or function.
2. Never create two DataStore instances for the same file name in the same process. That breaks its single-writer guarantee and throws IllegalStateException: There are multiple DataStores active for the same file.

The repository

package com.example.catalog.data
import android.util.Log
import androidx.datastore.core.DataStore
import androidx.datastore.preferences.core.Preferences
import androidx.datastore.preferences.core.booleanPreferencesKey
import androidx.datastore.preferences.core.edit
import androidx.datastore.preferences.core.emptyPreferences
import java.io.IOException
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.catch
import kotlinx.coroutines.flow.map
class UserPreferencesRepository(
 private val dataStore: DataStore<Preferences>
) {
 private companion object {
 val IS_LINEAR_LAYOUT = booleanPreferencesKey("is_linear_layout")
 const val TAG = "UserPreferencesRepo"
 }
 val isLinearLayout: Flow<Boolean> = dataStore.data
 .catch { e ->
 if (e is IOException) {
 Log.e(TAG, "Error reading preferences.", e)
 emit(emptyPreferences())
 } else {
 throw e
 }
 }
 .map { preferences ->
 preferences[IS_LINEAR_LAYOUT] ?: true
 }
 suspend fun saveLayoutPreference(isLinearLayout: Boolean) {
 dataStore.edit { preferences ->
 preferences[IS_LINEAR_LAYOUT] = isLinearLayout
 }
 }
}

Step through it:

Keys. A preference is identified by a typed key made with one of the helper functions: booleanPreferencesKey, intPreferencesKey, longPreferencesKey, floatPreferencesKey, doublePreferencesKey, stringPreferencesKey and stringSetPreferencesKey. The type is part of the key, so reading with the wrong type is a compile error. The key name ("is_linear_layout") is the label on disk: never change it later or users lose the saved value.

Reading. dataStore.data is a Flow<Preferences>. It emits the current preferences immediately and again every time any preference is edited, so your UI updates automatically. We:

• catch an IOException (a disk problem reading the file) and emit empty preferences, so the app falls back to defaults instead of crashing. Any other exception is rethrown, which keeps CancellationException behaving correctly (lesson 28).
• map the Preferences to the one value we want, using the elvis operator ?: true to supply a default when the key has never been written. The first time the app runs, nothing is stored, so the default matters.

Writing. dataStore.edit { } is a suspend function. The lambda receives mutable preferences, you assign with the key as an index (preferences[KEY] = value), and DataStore commits the whole block atomically. To clear a value use preferences.remove(KEY); to clear everything use preferences.clear().

Notice how little code that is, and how it matches the Repository pattern from lesson 30: the repository hides DataStore from the rest of the app.

Container or Application

class CatalogApplication : Application() {
 lateinit var userPreferencesRepository: UserPreferencesRepository
 override fun onCreate() {
 super.onCreate()
 userPreferencesRepository = UserPreferencesRepository(dataStore)
 }
}

Register it with android:name=".CatalogApplication" in the manifest (lesson 30). If you already have an AppContainer, add userPreferencesRepository there instead; the structure is the same.

ViewModel

package com.example.catalog.ui
import androidx.lifecycle.ViewModel
import androidx.lifecycle.ViewModelProvider
import androidx.lifecycle.ViewModelProvider.AndroidViewModelFactory.Companion.APPLICATION_KEY
import androidx.lifecycle.viewModelScope
import androidx.lifecycle.viewmodel.initializer
import androidx.lifecycle.viewmodel.viewModelFactory
import com.example.catalog.CatalogApplication
import com.example.catalog.data.UserPreferencesRepository
import kotlinx.coroutines.flow.SharingStarted
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.map
import kotlinx.coroutines.flow.stateIn
import kotlinx.coroutines.launch
data class CatalogUiState(val isLinearLayout: Boolean = true)
class CatalogViewModel(
 private val userPreferencesRepository: UserPreferencesRepository
) : ViewModel() {
 val uiState: StateFlow<CatalogUiState> =
 userPreferencesRepository.isLinearLayout
 .map { CatalogUiState(it) }
 .stateIn(
 scope = viewModelScope,
 started = SharingStarted.WhileSubscribed(5_000),
 initialValue = CatalogUiState()
 )
 fun selectLayout(isLinearLayout: Boolean) {
 viewModelScope.launch {
 userPreferencesRepository.saveLayoutPreference(isLinearLayout)
 }
 }
 companion object {
 val Factory: ViewModelProvider.Factory = viewModelFactory {
 initializer {
 val application = this[APPLICATION_KEY] as CatalogApplication
 CatalogViewModel(application.userPreferencesRepository)
 }
 }
 }
}

Observe the full loop, which is the whole lesson in one picture:

1. The user taps the toggle: the UI calls viewModel.selectLayout(false).
2. The ViewModel launches a coroutine and calls the repository's saveLayoutPreference.
3. DataStore writes to disk and then emits new data.
4. isLinearLayout maps it, stateIn publishes it, and collectAsStateWithLifecycle() hands it to Compose.
5. The screen recomposes with the other layout.

Notice that the UI never sets the layout directly. It only reads state and reports events (unidirectional data flow, lesson 24). That is why the layout survives rotation, process death and a full phone restart.

The initialValue is shown for a split second before the first emission arrives from disk. Choose it so there is no ugly flash: using the same default as the repository (true) avoids a visible jump for first-time users.

The toggle in Compose

import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.GridView
import androidx.compose.material.icons.filled.ViewList
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.runtime.getValue
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import androidx.lifecycle.viewmodel.compose.viewModel
@Composable
fun CatalogApp(viewModel: CatalogViewModel = viewModel(factory = CatalogViewModel.Factory)) {
 val uiState by viewModel.uiState.collectAsStateWithLifecycle()
 Scaffold(
 topBar = {
 CenterAlignedTopAppBar(
 title = { Text("Catalog") },
 actions = {
 IconButton(onClick = { viewModel.selectLayout(!uiState.isLinearLayout) }) {
 Icon(
 imageVector = if (uiState.isLinearLayout) Icons.Filled.GridView
 else Icons.Filled.ViewList,
 contentDescription = if (uiState.isLinearLayout) "Switch to grid" else "Switch to list"
 )
 }
 }
 )
 }
 ) { innerPadding ->
 if (uiState.isLinearLayout) CatalogList(Modifier.padding(innerPadding))
 else CatalogGrid(Modifier.padding(innerPadding))
 }
}

(GridView and ViewList come from the extended icon set; add material-icons-extended or use your own vector assets. CenterAlignedTopAppBar needs @OptIn(ExperimentalMaterial3Api::class) in many Material 3 versions.) The two content composables are the LazyColumn and LazyVerticalGrid from lesson 21. Notice the content description changes with the state, which tells screen-reader users what the button will do (lesson 47).

Run it. Switch to grid, close the app from recents, reopen: the grid is still there. Now stop the app with adb shell am kill or restart the emulator: still there. That is persistence.

Real apps often need several settings. Two common approaches:

// Approach 1: many keys in one DataStore, one Flow per setting
val darkTheme: Flow<Boolean> = dataStore.data.map { it[DARK_THEME] ?: false }
val username: Flow<String> = dataStore.data.map { it[USERNAME] ?: "" }
// Approach 2: map once into a settings object
data class UserSettings(val darkTheme: Boolean = false, val username: String = "", val fontScale: Float = 1f)
val settings: Flow<UserSettings> = dataStore.data
 .catch { if (it is IOException) emit(emptyPreferences()) else throw it }
 .map { prefs ->
 UserSettings(
 darkTheme = prefs[DARK_THEME] ?: false,
 username = prefs[USERNAME] ?: "",
 fontScale = prefs[FONT_SCALE] ?: 1f
 )
 }

Approach 2 is usually cleaner: one stream, one immutable object, and a single place for defaults. Use distinctUntilChanged() if a particular consumer should not be woken by unrelated changes. For several writes that belong together, put them in one edit { } block so they are applied atomically.

Proto DataStore stores a typed object instead of loose keys. You define a schema (traditionally with Protocol Buffers; it can also use a Kotlin serializable class with a custom Serializer), and you read and write whole objects safely, with defaults and versioning.

For this course Preferences DataStore is enough. Reach for Proto DataStore when your settings become a structured document that you want to evolve safely, and read the current official guide first, since its setup is more involved.

Migrating from SharedPreferences

If an existing app already stores settings in SharedPreferences, DataStore can import them once with a SharedPreferencesMigration, passed to the delegate:

val Context.dataStore by preferencesDataStore(
 name = "settings",
 produceMigrations = { context ->
 listOf(SharedPreferencesMigration(context, "old_prefs_file_name"))
 }
)

The migration runs before the first read, copies the values, and (by default) removes them from the old file, so users keep their settings across the upgrade.

Because the repository takes a DataStore<Preferences> in its constructor, a test can make its own DataStore backed by a temporary file. The androidx.datastore:datastore-preferences-core artifact offers PreferenceDataStoreFactory:

import androidx.datastore.core.DataStore
import androidx.datastore.preferences.core.PreferenceDataStoreFactory
import androidx.datastore.preferences.core.Preferences
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.SupervisorJob
import kotlinx.coroutines.flow.first
import kotlinx.coroutines.test.runTest
import org.junit.Assert.assertEquals
import org.junit.Assert.assertFalse
import org.junit.Rule
import org.junit.Test
import org.junit.rules.TemporaryFolder
class UserPreferencesRepositoryTest {
 @get:Rule val tmp = TemporaryFolder()
 private fun createDataStore(scope: CoroutineScope): DataStore<Preferences> =
 PreferenceDataStoreFactory.create(scope = scope) { tmp.newFile("test.preferences_pb") }
 @Test
 fun defaultsToLinearLayout() = runTest {
 val repo = UserPreferencesRepository(createDataStore(backgroundScope))
 assertEquals(true, repo.isLinearLayout.first())
 }
 @Test
 fun savedChoiceIsReadBack() = runTest {
 val repo = UserPreferencesRepository(createDataStore(backgroundScope))
 repo.saveLayoutPreference(false)
 assertFalse(repo.isLinearLayout.first())
 }
}

backgroundScope is provided by runTest; coroutines launched in it are cancelled automatically when the test ends, which is what DataStore needs for its internal work. Check the current DataStore testing documentation if the factory signature in your version differs.

The capstone of Unit 6 is the Flight Search app. This is a planning-first project: read the brief, design on paper, then build.

The brief. The app has a search box. As the user types an airport name or its three-letter IATA code, a list of suggestions appears (ordered by how many passengers each airport handles). Tapping a suggestion shows flights from that airport to every other airport in the database. Each flight can be marked as a favourite, and when the search box is empty the user sees their saved favourites. The text in the search box is remembered the next time the app starts.

Data. You need a table of airports (id, name, IATA code, passenger count) and a table of favourites (id, departure code, destination code). Create your own sample airports data; the official course supplies a starter database, which you should obtain from the official pathway page.

Design questions to answer before coding:

1. Is a flight a table row? (Hint: no. It is a pair of airports, computed, not stored. Only favourites are stored.)
2. What happens when the search text is empty: suggestions or favourites?
3. When the user picks an airport, does the text field keep their typed text or fill in the full name? Where is that state kept?
4. How do you avoid a flash of "no favourites" before the first database read finishes?

Mistake #1: Creating more than one DataStore for the same file. Symptom: There are multiple DataStores active for the same file. The fix: a single top-level by preferencesDataStore(...) delegate per file.

Mistake #2: Declaring the delegate inside a class. What happens: a new instance each time. The fix: top level, once.

Mistake #3: Forgetting a default. What happens: nulls or wrong first-run values. The fix: ?: default.

Mistake #4: Renaming a key. What happens: users silently lose their saved preference. The fix: treat keys as permanent, or write a migration.

Mistake #5: Not handling IOException. What happens: a corrupt or unreadable file crashes the app. The fix: catch and emit empty preferences.

Mistake #6: Swallowing all exceptions in catch. What happens: cancellation and real bugs vanish. The fix: rethrow anything that is not an IOException.

Mistake #7: Read-then-write across two calls. What happens: lost updates. The fix: do the whole change inside one edit { }.

Mistake #8: Storing big data or secrets. What happens: slow reads, and plain-text secrets. The fix: Room or files for large data; secure storage for secrets.

Mistake #9: Reading the preference with first() in the UI. What happens: the screen never updates when the value changes. The fix: collect the Flow as state.

Mistake #10: Blocking with runBlocking to "get the value". What happens: the UI thread blocks. The fix: stay in coroutines and Flow.

Question 1. When should you choose DataStore over Room?

Question 2. Why is DataStore safer than SharedPreferences?

Question 3. What does dataStore.edit { } guarantee?

Question 4. Why must there be only one DataStore instance per file?

Question 5. What value does the first read return for a key that was never written, and how do you control it?

Go deeper: official resources

• Android Basics with Compose, Unit 6, Pathway 3: DataStore: the official pathway including Flight Search.
• Save preferences locally with DataStore codelab
• DataStore release notes
• Data layer guide