react-native/docs/asyncstorage.md

---
id: asyncstorage

title: asyncstorage
---
<a id="content"></a><h1>AsyncStorage</h1><div><div><p>AsyncStorage is a simple, asynchronous, persistent, key-value storage
system that is global to the app.  It should be used instead of LocalStorage.</p><p>It is recommended that you use an abstraction on top of AsyncStorage instead
of AsyncStorage directly for anything more than light usage since it
operates globally.</p><p>This JS code is a simple facade over the native iOS implementation to provide
a clear JS API, real Error objects, and simple non-multi functions. Each
method returns a <code>Promise</code> object.</p></div><span><h3><a class="anchor" name="methods"></a>Methods <a class="hash-link" href="#methods">#</a></h3><div class="props"><div class="prop"><h4 class="propTitle"><a class="anchor" name="getitem"></a><span class="propType">static </span>getItem<span class="propType">(key: string, callback?: ?(error: ?Error, result: ?string) =&gt; void)</span> <a class="hash-link" href="#getitem">#</a></h4><div><p>Fetches <code>key</code> and passes the result to <code>callback</code>, along with an <code>Error</code> if
there is any. Returns a <code>Promise</code> object.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="setitem"></a><span class="propType">static </span>setItem<span class="propType">(key: string, value: string, callback?: ?(error: ?Error) =&gt; void)</span> <a class="hash-link" href="#setitem">#</a></h4><div><p>Sets <code>value</code> for <code>key</code> and calls <code>callback</code> on completion, along with an
<code>Error</code> if there is any. Returns a <code>Promise</code> object.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="removeitem"></a><span class="propType">static </span>removeItem<span class="propType">(key: string, callback?: ?(error: ?Error) =&gt; void)</span> <a class="hash-link" href="#removeitem">#</a></h4><div><p>Returns a <code>Promise</code> object.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="mergeitem"></a><span class="propType">static </span>mergeItem<span class="propType">(key: string, value: string, callback?: ?(error: ?Error) =&gt; void)</span> <a class="hash-link" href="#mergeitem">#</a></h4><div><p>Merges existing value with input value, assuming they are stringified json.
Returns a <code>Promise</code> object. Not supported by all native implementations.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="clear"></a><span class="propType">static </span>clear<span class="propType">(callback?: ?(error: ?Error) =&gt; void)</span> <a class="hash-link" href="#clear">#</a></h4><div><p>Erases <em>all</em> AsyncStorage for all clients, libraries, etc.  You probably
don't want to call this - use removeItem or multiRemove to clear only your
own keys instead. Returns a <code>Promise</code> object.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="getallkeys"></a><span class="propType">static </span>getAllKeys<span class="propType">(callback?: ?(error: ?Error, keys: ?Array&lt;string&gt;) =&gt; void)</span> <a class="hash-link" href="#getallkeys">#</a></h4><div><p>Gets <em>all</em> keys known to the app, for all callers, libraries, etc. Returns a <code>Promise</code> object.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="flushgetrequests"></a><span class="propType">static </span>flushGetRequests<span class="propType">()</span> <a class="hash-link" href="#flushgetrequests">#</a></h4><div><p>Flushes any pending requests using a single multiget</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="multiget"></a><span class="propType">static </span>multiGet<span class="propType">(keys: Array&lt;string&gt;, callback?: ?(errors: ?Array&lt;Error&gt;, result: ?Array&lt;Array&lt;string&gt;&gt;) =&gt; void)</span> <a class="hash-link" href="#multiget">#</a></h4><div><p>multiGet invokes callback with an array of key-value pair arrays that
matches the input format of multiSet. Returns a <code>Promise</code> object.</p><p>  multiGet(['k1', 'k2'], cb) -&gt; cb([['k1', 'val1'], ['k2', 'val2']])</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="multiset"></a><span class="propType">static </span>multiSet<span class="propType">(keyValuePairs: Array&lt;Array&lt;string&gt;&gt;, callback?: ?(errors: ?Array&lt;Error&gt;) =&gt; void)</span> <a class="hash-link" href="#multiset">#</a></h4><div><p>multiSet and multiMerge take arrays of key-value array pairs that match
the output of multiGet, e.g. Returns a <code>Promise</code> object.</p><p>  multiSet([['k1', 'val1'], ['k2', 'val2']], cb);</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="multiremove"></a><span class="propType">static </span>multiRemove<span class="propType">(keys: Array&lt;string&gt;, callback?: ?(errors: ?Array&lt;Error&gt;) =&gt; void)</span> <a class="hash-link" href="#multiremove">#</a></h4><div><p>Delete all the keys in the <code>keys</code> array. Returns a <code>Promise</code> object.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="multimerge"></a><span class="propType">static </span>multiMerge<span class="propType">(keyValuePairs: Array&lt;Array&lt;string&gt;&gt;, callback?: ?(errors: ?Array&lt;Error&gt;) =&gt; void)</span> <a class="hash-link" href="#multimerge">#</a></h4><div><p>Merges existing values with input values, assuming they are stringified
json. Returns a <code>Promise</code> object.</p><p>Not supported by all native implementations.</p></div></div></div></span><span><h3><a class="anchor" name="properties"></a>Properties <a class="hash-link" href="#properties">#</a></h3><div class="props"></div></span></div><div><h3><a class="anchor" name="examples"></a><a class="edit-github" href="https://github.com/facebook/react-native/blob/master/Examples/UIExplorer/AsyncStorageExample.js">Edit on GitHub</a>Examples <a class="hash-link" href="#examples">#</a></h3><div class="prism language-javascript"><span class="token string">'use strict'</span><span class="token punctuation">;</span>

<span class="token keyword">var</span> React <span class="token operator">=</span> <span class="token function">require<span class="token punctuation">(</span></span><span class="token string">'react-native'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token keyword">var</span> <span class="token punctuation">{</span>
  AsyncStorage<span class="token punctuation">,</span>
  PickerIOS<span class="token punctuation">,</span>
  Text<span class="token punctuation">,</span>
  View
<span class="token punctuation">}</span> <span class="token operator">=</span> React<span class="token punctuation">;</span>
<span class="token keyword">var</span> PickerItemIOS <span class="token operator">=</span> PickerIOS<span class="token punctuation">.</span>Item<span class="token punctuation">;</span>

<span class="token keyword">var</span> STORAGE_KEY <span class="token operator">=</span> <span class="token string">'@AsyncStorageExample:key'</span><span class="token punctuation">;</span>
<span class="token keyword">var</span> COLORS <span class="token operator">=</span> <span class="token punctuation">[</span><span class="token string">'red'</span><span class="token punctuation">,</span> <span class="token string">'orange'</span><span class="token punctuation">,</span> <span class="token string">'yellow'</span><span class="token punctuation">,</span> <span class="token string">'green'</span><span class="token punctuation">,</span> <span class="token string">'blue'</span><span class="token punctuation">]</span><span class="token punctuation">;</span>

<span class="token keyword">var</span> BasicStorageExample <span class="token operator">=</span> React<span class="token punctuation">.</span><span class="token function">createClass<span class="token punctuation">(</span></span><span class="token punctuation">{</span>
  <span class="token function">componentDidMount<span class="token punctuation">(</span></span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
    <span class="token keyword">this</span><span class="token punctuation">.</span><span class="token function">_loadInitialState<span class="token punctuation">(</span></span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">done<span class="token punctuation">(</span></span><span class="token punctuation">)</span><span class="token punctuation">;</span>
  <span class="token punctuation">}</span><span class="token punctuation">,</span>

  async <span class="token function">_loadInitialState<span class="token punctuation">(</span></span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
    <span class="token keyword">try</span> <span class="token punctuation">{</span>
      <span class="token keyword">var</span> value <span class="token operator">=</span> await AsyncStorage<span class="token punctuation">.</span><span class="token function">getItem<span class="token punctuation">(</span></span>STORAGE_KEY<span class="token punctuation">)</span><span class="token punctuation">;</span>
      <span class="token keyword">if</span> <span class="token punctuation">(</span>value <span class="token operator">!</span><span class="token operator">==</span> <span class="token keyword">null</span><span class="token punctuation">)</span><span class="token punctuation">{</span>
        <span class="token keyword">this</span><span class="token punctuation">.</span><span class="token function">setState<span class="token punctuation">(</span></span><span class="token punctuation">{</span>selectedValue<span class="token punctuation">:</span> value<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
        <span class="token keyword">this</span><span class="token punctuation">.</span><span class="token function">_appendMessage<span class="token punctuation">(</span></span><span class="token string">'Recovered selection from disk: '</span> <span class="token operator">+</span> value<span class="token punctuation">)</span><span class="token punctuation">;</span>
      <span class="token punctuation">}</span> <span class="token keyword">else</span> <span class="token punctuation">{</span>
        <span class="token keyword">this</span><span class="token punctuation">.</span><span class="token function">_appendMessage<span class="token punctuation">(</span></span><span class="token string">'Initialized with no selection on disk.'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
      <span class="token punctuation">}</span>
    <span class="token punctuation">}</span> <span class="token keyword">catch</span> <span class="token punctuation">(</span><span class="token class-name">error</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
      <span class="token keyword">this</span><span class="token punctuation">.</span><span class="token function">_appendMessage<span class="token punctuation">(</span></span><span class="token string">'AsyncStorage error: '</span> <span class="token operator">+</span> error<span class="token punctuation">.</span>message<span class="token punctuation">)</span><span class="token punctuation">;</span>
    <span class="token punctuation">}</span>
  <span class="token punctuation">}</span><span class="token punctuation">,</span>

  <span class="token function">getInitialState<span class="token punctuation">(</span></span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
    <span class="token keyword">return</span> <span class="token punctuation">{</span>
      selectedValue<span class="token punctuation">:</span> COLORS<span class="token punctuation">[</span><span class="token number">0</span><span class="token punctuation">]</span><span class="token punctuation">,</span>
      messages<span class="token punctuation">:</span> <span class="token punctuation">[</span><span class="token punctuation">]</span><span class="token punctuation">,</span>
    <span class="token punctuation">}</span><span class="token punctuation">;</span>
  <span class="token punctuation">}</span><span class="token punctuation">,</span>

  <span class="token function">render<span class="token punctuation">(</span></span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
    <span class="token keyword">var</span> color <span class="token operator">=</span> <span class="token keyword">this</span><span class="token punctuation">.</span>state<span class="token punctuation">.</span>selectedValue<span class="token punctuation">;</span>
    <span class="token keyword">return</span> <span class="token punctuation">(</span>
      &lt;View<span class="token operator">&gt;</span>
        &lt;PickerIOS
          selectedValue<span class="token operator">=</span><span class="token punctuation">{</span>color<span class="token punctuation">}</span>
          onValueChange<span class="token operator">=</span><span class="token punctuation">{</span><span class="token keyword">this</span><span class="token punctuation">.</span>_onValueChange<span class="token punctuation">}</span><span class="token operator">&gt;</span>
          <span class="token punctuation">{</span>COLORS<span class="token punctuation">.</span><span class="token function">map<span class="token punctuation">(</span></span><span class="token punctuation">(</span>value<span class="token punctuation">)</span> <span class="token operator">=</span><span class="token operator">&gt;</span> <span class="token punctuation">(</span>
            &lt;PickerItemIOS
              key<span class="token operator">=</span><span class="token punctuation">{</span>value<span class="token punctuation">}</span>
              value<span class="token operator">=</span><span class="token punctuation">{</span>value<span class="token punctuation">}</span>
              label<span class="token operator">=</span><span class="token punctuation">{</span>value<span class="token punctuation">}</span>
            <span class="token operator">/</span><span class="token operator">&gt;</span>
          <span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">}</span>
        &lt;<span class="token operator">/</span>PickerIOS<span class="token operator">&gt;</span>
        &lt;Text<span class="token operator">&gt;</span>
          <span class="token punctuation">{</span><span class="token string">'Selected: '</span><span class="token punctuation">}</span>
          &lt;Text style<span class="token operator">=</span><span class="token punctuation">{</span><span class="token punctuation">{</span>color<span class="token punctuation">}</span><span class="token punctuation">}</span><span class="token operator">&gt;</span>
            <span class="token punctuation">{</span><span class="token keyword">this</span><span class="token punctuation">.</span>state<span class="token punctuation">.</span>selectedValue<span class="token punctuation">}</span>
          &lt;<span class="token operator">/</span>Text<span class="token operator">&gt;</span>
        &lt;<span class="token operator">/</span>Text<span class="token operator">&gt;</span>
        &lt;Text<span class="token operator">&gt;</span><span class="token punctuation">{</span><span class="token string">' '</span><span class="token punctuation">}</span>&lt;<span class="token operator">/</span>Text<span class="token operator">&gt;</span>
        &lt;Text onPress<span class="token operator">=</span><span class="token punctuation">{</span><span class="token keyword">this</span><span class="token punctuation">.</span>_removeStorage<span class="token punctuation">}</span><span class="token operator">&gt;</span>
          Press here to remove from storage<span class="token punctuation">.</span>
        &lt;<span class="token operator">/</span>Text<span class="token operator">&gt;</span>
        &lt;Text<span class="token operator">&gt;</span><span class="token punctuation">{</span><span class="token string">' '</span><span class="token punctuation">}</span>&lt;<span class="token operator">/</span>Text<span class="token operator">&gt;</span>
        &lt;Text<span class="token operator">&gt;</span>Messages<span class="token punctuation">:</span>&lt;<span class="token operator">/</span>Text<span class="token operator">&gt;</span>
        <span class="token punctuation">{</span><span class="token keyword">this</span><span class="token punctuation">.</span>state<span class="token punctuation">.</span>messages<span class="token punctuation">.</span><span class="token function">map<span class="token punctuation">(</span></span><span class="token punctuation">(</span>m<span class="token punctuation">)</span> <span class="token operator">=</span><span class="token operator">&gt;</span> &lt;Text key<span class="token operator">=</span><span class="token punctuation">{</span>m<span class="token punctuation">}</span><span class="token operator">&gt;</span><span class="token punctuation">{</span>m<span class="token punctuation">}</span>&lt;<span class="token operator">/</span>Text<span class="token operator">&gt;</span><span class="token punctuation">)</span><span class="token punctuation">}</span>
      &lt;<span class="token operator">/</span>View<span class="token operator">&gt;</span>
    <span class="token punctuation">)</span><span class="token punctuation">;</span>
  <span class="token punctuation">}</span><span class="token punctuation">,</span>

  async <span class="token function">_onValueChange<span class="token punctuation">(</span></span>selectedValue<span class="token punctuation">)</span> <span class="token punctuation">{</span>
    <span class="token keyword">this</span><span class="token punctuation">.</span><span class="token function">setState<span class="token punctuation">(</span></span><span class="token punctuation">{</span>selectedValue<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
    <span class="token keyword">try</span> <span class="token punctuation">{</span>
      await AsyncStorage<span class="token punctuation">.</span><span class="token function">setItem<span class="token punctuation">(</span></span>STORAGE_KEY<span class="token punctuation">,</span> selectedValue<span class="token punctuation">)</span><span class="token punctuation">;</span>
      <span class="token keyword">this</span><span class="token punctuation">.</span><span class="token function">_appendMessage<span class="token punctuation">(</span></span><span class="token string">'Saved selection to disk: '</span> <span class="token operator">+</span> selectedValue<span class="token punctuation">)</span><span class="token punctuation">;</span>
    <span class="token punctuation">}</span> <span class="token keyword">catch</span> <span class="token punctuation">(</span><span class="token class-name">error</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
      <span class="token keyword">this</span><span class="token punctuation">.</span><span class="token function">_appendMessage<span class="token punctuation">(</span></span><span class="token string">'AsyncStorage error: '</span> <span class="token operator">+</span> error<span class="token punctuation">.</span>message<span class="token punctuation">)</span><span class="token punctuation">;</span>
    <span class="token punctuation">}</span>
  <span class="token punctuation">}</span><span class="token punctuation">,</span>

  async <span class="token function">_removeStorage<span class="token punctuation">(</span></span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
    <span class="token keyword">try</span> <span class="token punctuation">{</span>
      await AsyncStorage<span class="token punctuation">.</span><span class="token function">removeItem<span class="token punctuation">(</span></span>STORAGE_KEY<span class="token punctuation">)</span><span class="token punctuation">;</span>
      <span class="token keyword">this</span><span class="token punctuation">.</span><span class="token function">_appendMessage<span class="token punctuation">(</span></span><span class="token string">'Selection removed from disk.'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
    <span class="token punctuation">}</span> <span class="token keyword">catch</span> <span class="token punctuation">(</span><span class="token class-name">error</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
      <span class="token keyword">this</span><span class="token punctuation">.</span><span class="token function">_appendMessage<span class="token punctuation">(</span></span><span class="token string">'AsyncStorage error: '</span> <span class="token operator">+</span> error<span class="token punctuation">.</span>message<span class="token punctuation">)</span><span class="token punctuation">;</span>
    <span class="token punctuation">}</span>
  <span class="token punctuation">}</span><span class="token punctuation">,</span>

  <span class="token function">_appendMessage<span class="token punctuation">(</span></span>message<span class="token punctuation">)</span> <span class="token punctuation">{</span>
    <span class="token keyword">this</span><span class="token punctuation">.</span><span class="token function">setState<span class="token punctuation">(</span></span><span class="token punctuation">{</span>messages<span class="token punctuation">:</span> <span class="token keyword">this</span><span class="token punctuation">.</span>state<span class="token punctuation">.</span>messages<span class="token punctuation">.</span><span class="token function">concat<span class="token punctuation">(</span></span>message<span class="token punctuation">)</span><span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
  <span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

exports<span class="token punctuation">.</span>title <span class="token operator">=</span> <span class="token string">'AsyncStorage'</span><span class="token punctuation">;</span>
exports<span class="token punctuation">.</span>description <span class="token operator">=</span> <span class="token string">'Asynchronous local disk storage.'</span><span class="token punctuation">;</span>
exports<span class="token punctuation">.</span>examples <span class="token operator">=</span> <span class="token punctuation">[</span>
  <span class="token punctuation">{</span>
    title<span class="token punctuation">:</span> <span class="token string">'Basics - getItem, setItem, removeItem'</span><span class="token punctuation">,</span>
    <span class="token function">render<span class="token punctuation">(</span></span><span class="token punctuation">)</span><span class="token punctuation">:</span> ReactElement <span class="token punctuation">{</span> <span class="token keyword">return</span> &lt;BasicStorageExample <span class="token operator">/</span><span class="token operator">&gt;</span><span class="token punctuation">;</span> <span class="token punctuation">}</span>
  <span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token punctuation">]</span><span class="token punctuation">;</span></div></div><div class="docs-prevnext"><a class="docs-next" href="backandroid.html#content">Next →</a></div>