DataStore for Preferences
DataStore is Jetpack's replacement for SharedPreferences, designed to fix the older API's biggest problems: SharedPreferences.apply() writes to disk on a background thread but offers no signal for completion or failure, its getters run synchronously and can block the calling thread on first access, and it has no built-in mechanism for atomic, transactional updates across multiple keys. DataStore comes in two flavors — Preferences DataStore, which stores untyped key-value pairs similar to SharedPreferences but through a fully asynchronous Flow-based API, and Proto DataStore, which stores strongly typed objects defined via Protocol Buffers, gaining compile-time schema safety at the cost of extra setup. Both variants persist data through Kotlin coroutines and expose the current value as a Flow, so reads are inherently asynchronous and observable, and writes go through a suspend function that only returns once the change is durably applied.
Cricket analogy: SharedPreferences.apply() writing silently is like a scorer jotting a run down without confirming the umpire signaled it, while DataStore's Flow-based writes are like waiting for the third umpire's confirmed decision before updating the board.
Reading and writing with Preferences DataStore
A Preferences DataStore instance is typically created once per app process via the property delegate preferencesDataStore(name = ...) on Context. Keys are declared with typed helpers such as stringPreferencesKey, intPreferencesKey, or booleanPreferencesKey, which prevents accidentally reading a String value as an Int. Reading a value means collecting dataStore.data, a Flow<Preferences>, and mapping out the specific key you care about; because it's a Flow, any UI observing it recomposes automatically whenever the value changes elsewhere in the app. Writing uses dataStore.edit { prefs -> ... }, a suspend function that applies the given transform block atomically — either the whole block succeeds and is persisted, or none of it is, which eliminates the partial-write races that plagued raw SharedPreferences.Editor usage under concurrent access.
Cricket analogy: stringPreferencesKey vs intPreferencesKey is like a scorebook enforcing that 'batsman name' columns can't accidentally hold a run count, preventing a scorer from writing '45' into the wrong column.
private val Context.userPrefsDataStore by preferencesDataStore(name = "user_prefs")
object PrefsKeys {
val DARK_MODE = booleanPreferencesKey("dark_mode")
val USERNAME = stringPreferencesKey("username")
}
class UserPreferencesRepository(private val context: Context) {
val isDarkMode: Flow<Boolean> = context.userPrefsDataStore.data
.map { prefs -> prefs[PrefsKeys.DARK_MODE] ?: false }
suspend fun setDarkMode(enabled: Boolean) {
context.userPrefsDataStore.edit { prefs ->
prefs[PrefsKeys.DARK_MODE] = enabled
}
}
suspend fun setUsername(name: String) {
context.userPrefsDataStore.edit { prefs ->
prefs[PrefsKeys.USERNAME] = name
}
}
}Preferences DataStore vs. Proto DataStore
Preferences DataStore is the closer drop-in replacement for SharedPreferences and is the right default for simple flags, small settings, and toggles where a loose key-value model is acceptable. Proto DataStore requires defining a .proto schema and generating a typed data class from it, which adds build tooling overhead but gives you compile-time guarantees that every read and write matches a fixed schema — valuable when the stored data is structurally complex, like a whole settings object with nested fields, where a typo'd string key in Preferences DataStore would otherwise be a silent runtime bug.
Cricket analogy: Preferences DataStore for simple toggles is like a scorer using a loose tally sheet for quick notes, while Proto DataStore's generated schema is like an official ICC scorecard with fixed, validated fields for a full Test match record.
Think of Preferences DataStore as SharedPreferences with coroutines and Flow bolted on properly, and Proto DataStore as a fully typed, schema-validated settings object — the same relationship Room has to raw SQLite.
DataStore does not support partial updates to large, complex objects efficiently the way a database does — every read of dataStore.data emits the entire Preferences object. For data with relational structure or that needs querying, prefer Room; reserve DataStore for small, flat, app-wide settings.
- DataStore replaces SharedPreferences with a fully asynchronous, coroutine- and Flow-based API.
- Preferences DataStore stores untyped key-value pairs; Proto DataStore stores strongly typed, schema-defined objects.
- dataStore.data exposes a Flow<Preferences> so reads are observable and drive automatic recomposition.
- dataStore.edit { } is a suspend function that applies updates atomically and transactionally.
- Typed key helpers like stringPreferencesKey prevent type-mismatch bugs that plain string keys allowed in SharedPreferences.
- DataStore is best for small, flat settings; structured or queryable data belongs in Room.
Practice what you learned
1. What is the primary limitation of SharedPreferences that DataStore was designed to fix?
2. What does dataStore.data return?
3. Why is dataStore.edit { } considered safer than repeated SharedPreferences.Editor calls under concurrency?
4. When is Proto DataStore preferable to Preferences DataStore?
5. For what kind of data is DataStore explicitly NOT the right tool, according to best practice?
Was this page helpful?
You May Also Like
Room Database Basics
Room is Jetpack's SQLite abstraction layer that provides compile-time query verification, entity mapping, and Flow-based observation for reactive Android persistence.
Kotlin Flow Fundamentals
Flow is Kotlin's asynchronous stream type for emitting multiple sequential values over time, built on coroutines, and central to reactive state management in Android apps.
Repository Pattern in Android
The repository pattern centralizes data access behind a single abstraction, hiding whether data comes from Room, Retrofit, or DataStore from ViewModels and the UI layer.
stateIn and shareIn
stateIn and shareIn convert cold Flows into hot, shareable StateFlow and SharedFlow instances, with SharingStarted policies controlling exactly when the underlying producer runs.