README.md

Compose Settings - Multiplatform

Versions

This library provides a set of Settings like composable items to help android Jetpack Compose developers build complex settings screens without all the boilerplate

Install

allprojects {
  repositories {
    //...
    mavenCentral()
  }
}

Add dependencies:

Material 2 version
implementation 'com.github.alorma:compose-settings-ui:$version'

Material 3 version
implementation 'com.github.alorma:compose-settings-ui-m3:$version'

Demo

Menu link	Switch	Checkbox

Usage

This library provide some @Composable items that can be used to build your settings screen.

Scaffold, Column... is not provided by the library, you can place items wherever you want.

Menu Link

Android docs

This can be used to open another settings screen, open link, show a dialog...

SettingsMenuLink(
  icon = { Icon(imageVector = Icons.Default.Wifi, contentDescription = "Wifi") },
  title = { Text(text = "Hello") },
  subtitle = { Text(text = "This is a longer text") },
  onClick = {},
)

action can be provided:

SettingsMenuLink(
  title = { Text(text = "Menu 4") },
  action = { ... },
)

Switch && Checkboxes

Android docs - Switch

Android docs - Checkbox

This can be used to enable or disable a feature

SettingsCheckbox(
  icon = { Icon(imageVector = Icons.Default.Wifi, contentDescription = "Wifi") },
  title = { Text(text = "Hello") },
  subtitle = { Text(text = "This is a longer text") },
  onCheckedChange = { newValue -> },
)

SettingsCheckbox(
  icon = { Icon(imageVector = Icons.Default.Wifi, contentDescription = "Wifi") },
  title = { Text(text = "Hello") },
  subtitle = { Text(text = "This is a longer text") },
  onCheckedChange = { newValue -> },
)

State

In order to provide a default value for the setting and recompose when state changes, you must use state parameter.

Installation

implementation 'com.github.alorma:compose-settings-storage-preferences:$version'

val state = rememberBooleanSettingState()
SettingsCheckbox(state = state)

val state = rememberFloatSettingState()
SettingSlider(state = state)

And, you can react to state change, for example:

val state = rememberBooleanSettingState()

if (state.value) {
  Text("Enabled")
} else {
  Text("Disabled")
}

val state = rememberBooleanSettingState()

if (state.value > 0.5f) {
  Icon(imageVector = Icons.Default.BrightnessLow)
} else {
  Icon(imageVector = Icons.Default.BrightnessHigh)
}

This library provide default value for state as false, however if you need to pass a different value (true), you can use:

val state = rememberBooleanSettingState(defaultValue = true)
val state = rememberFloatSettingState(defaultValue = 0.1f)

The library provides a preferences version of the state, so when setting state is changed, the value is persisted on the preferences.

val state = rememberPreferenceBooleanSettingState(key = "pref_key", defaultValue = true)
val state = rememberPreferenceFloatSettingState(key = "pref_key", defaultValue = 0.1f)
val state = rememberPreferenceIntSettingState(key = "pref_key", defaultValue = 1)

Also, the library provides a DataStore (Both Preference and Proto) version of the state, so when setting state is changed, the value is persisted on the DataStore preferences.

Add dependencies:

PreferenceDataStore version
implementation 'com.github.alorma:compose-settings-storage-datastore:$version'

ProtoDatastore version
implementation 'com.github.alorma:compose-settings-storage-datastore-proto:$version'

And you have to add ProtoBuf dependencies in addition.

// PreferenceDataStore
val state = rememberPreferenceDataStoreBooleanSettingState(key = "pref_key", defaultValue = true)
val state = rememberPreferenceDataStoreFloatSettingState(key = "pref_key", defaultValue = 0.1f)
val state = rememberPreferenceDataStoreIntSettingState(key = "pref_key", defaultValue = 1)


// ProtoDataStore
val datastoreState = rememberProtoDataStoreState(
  // "filename" is optional, but it is recommended to set the protobuf file name so that it wouldn't conflict with other datastore definition.
  filename = "compose_settings_datastore_proto.pb",
  serializer = SettingsSerializer,
)

val state = rememberProtoDataStoreTransformSettingState(
  protoDataStoreState = dataStoreState,
  encoder = {savedValue, newValue -> savedValue.toBuilder().setProtoValue(newValue).build() },
  decoder = { it.protoValue }
)
val state = rememberProtoDataStoreSettingState(protoDataStoreState = dataStoreState)