# Settings Service

Last updated:

<!-- -->

October 18, 2026

<!-- -->

\| 3 minutes read

<br />

<br />

The Settings Service stores key-value pairs in permanent storage using the `SettingsService` class. Settings are saved in a `.ini` file format.

## Step 1: Create a Settings Service[​](#step-1-create-a-settings-service "Direct link to Step 1: Create a Settings Service")

Create or open a settings storage using the factory constructor of `SettingsService`. If no path is provided, a default one is used:

```dart
final settings = SettingsService();

```

You can provide a custom path:

```dart
final settings = SettingsService(path: "/custom/settings/path");

```

Access the current file path where settings are stored:

```dart
final String currentPath = settings.path;

```

## Step 2: Add and get values[​](#step-2-add-and-get-values "Direct link to Step 2: Add and get values")

Store various types of data using set methods:

```dart
settings.setString("username", "john_doe");
settings.setBool("isLoggedIn", true);
settings.setInt("launchCount", 5);
settings.setLargeInt("highScore", 1234567890123);
settings.setDouble("volume", 0.75);

```

Retrieve values using get methods. These methods accept an optional `defaultValue` parameter returned when the key is not found in the selected group. The `defaultValue` does not set the value.

```dart
final String username = settings.getString("username", defaultValue: "guest");
final bool isLoggedIn = settings.getBool("isLoggedIn", defaultValue: false);
final int launchCount = settings.getInt("launchCount", defaultValue: 0);
final int highScore = settings.getLargeInt("highScore", defaultValue: 0);
final double volume = settings.getDouble("volume", defaultValue: 1.0);

```

When you set a value on one type and get it on another type, a conversion occurs:

```dart
settings.setInt("count", 1234);

String value = settings.getString("count"); // Returns '1234'

```

Tip

Each change may take up to one second to be written to storage. Use the `flush` method to ensure changes are written to permanent storage immediately.

### Add and get multiple values at once[​](#add-and-get-multiple-values-at-once "Direct link to Add and get multiple values at once")

Use the `setStringList`, `setIntList`, `setLargeIntList`, `setBoolList`, and `setDoubleList` methods to store multiple values at once. The methods require a list of key-value pairs in the form of a `Map<String, T>`.

```dart
settings.setStringList([('key1', 'val1'), ('key2', 'val2')]);

```

Use the `getStringList`, `getIntList`, `getLargeIntList`, `getBoolList`, and `getDoubleList` methods to retrieve multiple values at once. The methods require a list of keys in the form of a `List<String>` and an optional `List<String>?` of default values. If the number of default values provided is invalid, the methods return empty list and set `ApiErrorService` to `GemError.invalidInput`. The returned list contains values in the same order as the provided keys.

```dart
settings.getStringList(['key1', 'key2', 'key3'], defaultValues: ['def1', 'def2', 'def3']);

```

The same conversion apply when getting/setting multiple values as when getting/setting single values.

## Step 3: Organize with groups[​](#step-3-organize-with-groups "Direct link to Step 3: Organize with groups")

Groups organize settings into logical units. The default group is `DEFAULT`. Only one group can be active at a time, and nested groups are not allowed.

```dart
// All operations above this are made inside DEFAULT
settings.beginGroup("USER_PREFERENCES");

// All operations here are made inside USER_PREFERENCES

settings.beginGroup("OTHER_SETTINGS");

// All operations here are made inside OTHER_SETTINGS

settings.endGroup();
// All operations above this are made inside DEFAULT

```

Get the current group using the `group` getter.

danger

The values passed to `beginGroup` are converted to upper-case.

Tip

A `flush` is automatically done after the group is changed.

## Step 4: Remove values[​](#step-4-remove-values "Direct link to Step 4: Remove values")

### Remove value by key[​](#remove-value-by-key "Direct link to Remove value by key")

The `remove` method accepts a key (or pattern) and returns the number of deleted entries from the current group:

```dart
final int removedCount = settings.remove("username");

```

### Clear all values[​](#clear-all-values "Direct link to Clear all values")

Use the `clear` method to remove all settings from all groups:

```dart
settings.clear();

```