Skip to main content
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us