Settings

Settings is iOS-only. On other platforms, it has no effect.

The Settings API provides access to iOS app settings stored in NSUserDefaults. It allows reading and writing settings values and observing changes to specific settings keys.

Import

import { Settings } from 'react-native';

Methods

`get()`

static get(key: string): any

Get the value for a given settings key. Parameters:

key: The settings key to retrieve

Returns: The value stored for the key, or undefined if not found.

Example

import { Settings } from 'react-native';

const username = Settings.get('username');
console.log(username);

`set()`

static set(settings: Object): void

Set multiple settings values at once. Parameters:

settings: An object containing key-value pairs to store

The set() method updates the local cache and persists values to NSUserDefaults.

Example

import { Settings } from 'react-native';

Settings.set({
  username: 'johndoe',
  theme: 'dark',
  notificationsEnabled: true,
});

`watchKeys()`

static watchKeys(
  keys: string | string[],
  callback: () => void
): number

Watch for changes to specific settings keys. Parameters:

keys: A single key string or array of key strings to watch
callback: Function called when any watched key changes

Returns: A watch ID that can be used with clearWatch() to unsubscribe.

Example

import { Settings } from 'react-native';

const watchId = Settings.watchKeys(['theme', 'fontSize'], () => {
  console.log('Theme or font size changed!');
  const theme = Settings.get('theme');
  const fontSize = Settings.get('fontSize');
  // Update UI based on new settings
});

`clearWatch()`

static clearWatch(watchId: number): void

Remove a settings key watcher. Parameters:

watchId: The watch ID returned by watchKeys()

Example

import { Settings } from 'react-native';

const watchId = Settings.watchKeys('theme', () => {
  console.log('Theme changed');
});

// Later, unsubscribe
Settings.clearWatch(watchId);

Usage Examples

Basic Settings Management

import React, { useEffect, useState } from 'react';
import { Settings, View, Text, Button } from 'react-native';

function App() {
  const [theme, setTheme] = useState(Settings.get('theme') || 'light');

  const toggleTheme = () => {
    const newTheme = theme === 'light' ? 'dark' : 'light';
    Settings.set({ theme: newTheme });
    setTheme(newTheme);
  };

  return (
    <View>
      <Text>Current Theme: {theme}</Text>
      <Button title="Toggle Theme" onPress={toggleTheme} />
    </View>
  );
}

export default App;

Watching Settings Changes

import React, { useEffect, useState } from 'react';
import { Settings, View, Text, Switch } from 'react-native';

function App() {
  const [notifications, setNotifications] = useState(
    Settings.get('notificationsEnabled') ?? true
  );

  useEffect(() => {
    const watchId = Settings.watchKeys('notificationsEnabled', () => {
      const value = Settings.get('notificationsEnabled');
      setNotifications(value);
      console.log('Notifications setting changed to:', value);
    });

    return () => {
      Settings.clearWatch(watchId);
    };
  }, []);

  const toggleNotifications = (value) => {
    Settings.set({ notificationsEnabled: value });
    setNotifications(value);
  };

  return (
    <View>
      <Text>Enable Notifications</Text>
      <Switch value={notifications} onValueChange={toggleNotifications} />
    </View>
  );
}

export default App;

Multiple Settings

import React, { useEffect, useState } from 'react';
import { Settings, View, Text, Button } from 'react-native';

function App() {
  const [userSettings, setUserSettings] = useState({
    username: Settings.get('username') || '',
    fontSize: Settings.get('fontSize') || 14,
    theme: Settings.get('theme') || 'light',
  });

  useEffect(() => {
    const watchId = Settings.watchKeys(
      ['username', 'fontSize', 'theme'],
      () => {
        setUserSettings({
          username: Settings.get('username') || '',
          fontSize: Settings.get('fontSize') || 14,
          theme: Settings.get('theme') || 'light',
        });
      }
    );

    return () => Settings.clearWatch(watchId);
  }, []);

  const updateSettings = () => {
    Settings.set({
      username: 'newuser',
      fontSize: 16,
      theme: 'dark',
    });
  };

  return (
    <View>
      <Text>Username: {userSettings.username}</Text>
      <Text>Font Size: {userSettings.fontSize}</Text>
      <Text>Theme: {userSettings.theme}</Text>
      <Button title="Update Settings" onPress={updateSettings} />
    </View>
  );
}

export default App;

User Preferences Hook

import { useEffect, useState } from 'react';
import { Settings } from 'react-native';

function useSettings(key, defaultValue) {
  const [value, setValue] = useState(Settings.get(key) ?? defaultValue);

  useEffect(() => {
    const watchId = Settings.watchKeys(key, () => {
      setValue(Settings.get(key) ?? defaultValue);
    });

    return () => Settings.clearWatch(watchId);
  }, [key, defaultValue]);

  const updateValue = (newValue) => {
    Settings.set({ [key]: newValue });
    setValue(newValue);
  };

  return [value, updateValue];
}

// Usage
function App() {
  const [theme, setTheme] = useSettings('theme', 'light');
  const [fontSize, setFontSize] = useSettings('fontSize', 14);

  return (
    <View>
      <Text>Theme: {theme}</Text>
      <Button title="Toggle Theme" onPress={() => {
        setTheme(theme === 'light' ? 'dark' : 'light');
      }} />
      
      <Text>Font Size: {fontSize}</Text>
      <Button title="Increase Font" onPress={() => {
        setFontSize(fontSize + 2);
      }} />
    </View>
  );
}

Persisting App State

import React, { useEffect, useState } from 'react';
import { Settings, View, Text, TextInput, Button } from 'react-native';

function App() {
  const [formData, setFormData] = useState({
    name: Settings.get('name') || '',
    email: Settings.get('email') || '',
  });

  const saveData = () => {
    Settings.set({
      name: formData.name,
      email: formData.email,
      lastSaved: new Date().toISOString(),
    });
    alert('Settings saved!');
  };

  const loadData = () => {
    setFormData({
      name: Settings.get('name') || '',
      email: Settings.get('email') || '',
    });
    const lastSaved = Settings.get('lastSaved');
    if (lastSaved) {
      console.log('Last saved:', lastSaved);
    }
  };

  useEffect(() => {
    loadData();
  }, []);

  return (
    <View>
      <TextInput
        placeholder="Name"
        value={formData.name}
        onChangeText={(name) => setFormData({ ...formData, name })}
      />
      <TextInput
        placeholder="Email"
        value={formData.email}
        onChangeText={(email) => setFormData({ ...formData, email })}
      />
      <Button title="Save" onPress={saveData} />
      <Button title="Load" onPress={loadData} />
    </View>
  );
}

export default App;

Notes

Settings only works on iOS and uses NSUserDefaults internally.
Values are automatically persisted across app launches.
Supported value types include strings, numbers, booleans, and objects (serializable to JSON).
Changes made via set() trigger callbacks registered with watchKeys().
The callback receives no arguments; use get() to retrieve updated values.
Watch IDs are integers starting from 0.
It’s important to call clearWatch() in cleanup functions to prevent memory leaks.
For cross-platform settings storage, consider using AsyncStorage or a third-party solution.
Settings are app-specific and not shared between apps.

Core APIs

Hooks

Interaction

Accessibility & Internationalization

Developer Tools

Networking

Storage

Android APIs

iOS APIs

Import

Methods

`get()`

Example

`set()`

Example

`watchKeys()`

Example

`clearWatch()`

Example

Usage Examples

Basic Settings Management

Watching Settings Changes

Multiple Settings

User Preferences Hook

Persisting App State

Notes

​Import

​Methods

​get()

​Example

​set()

​Example

​watchKeys()

​Example

​clearWatch()

​Example

​Usage Examples

​Basic Settings Management

​Watching Settings Changes

​Multiple Settings

​User Preferences Hook

​Persisting App State

​Notes

Import

Methods

`get()`

Example

`set()`

Example

`watchKeys()`

Example

`clearWatch()`

Example

Usage Examples

Basic Settings Management

Watching Settings Changes

Multiple Settings

User Preferences Hook

Persisting App State

Notes