access-custom-user-data.txt

.. _web-access-custom-user-data:

=================================
Access Custom User Data - Web SDK
=================================

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 2
   :class: singlecol

Overview
--------

You can read arbitrary data about your application users, known as custom user
data, directly within your web application. For example, you might store a
user's preferred language, date of birth, or local timezone.

Realm references a MongoDB collection in your linked cluster to find the custom
data for a given user but does not add or update any custom user data documents.
You are responsible for managing and updating user data in the collection. For
details on how to enable and configure custom user data, see :ref:`Enable Custom
User Data <custom-user-data>`

Example User Object
~~~~~~~~~~~~~~~~~~~

The code examples in this page use the following :ref:`user object
<user-objects>` on which the ``custom_data`` field has not yet been set.

.. code-block:: js

   {
     id: '5f1f216e82df4a7979f9da93',
     type: 'normal',
     data: { email: 'test@example.com' },
     custom_data: {
       _id: '5f20d083a37057d55edbdd57',
       userID: '5f1f216e82df4a7979f9da93',
       description: 'a test document for user: test@example.com',
     },
     identities: [
       { id: '5f1f216e82df4a7979f9da90', provider_type: 'local-userpass' }
     ]
   }

.. include:: /includes/use-custom-data-note.rst

.. _web-read-custom-user-data:

Read Custom User Data
---------------------

.. include:: /includes/custom-data-may-be-stale.rst

You can access a read-only copy of a logged in user's custom data directly from
the :js-sdk:`Realm.User.customData <Realm.User.html#customData>` property.

.. literalinclude:: /examples/generated/web/access-custom-user-data.snippet.read-custom-user-data.js
   :language: javascript

To manually fetch the latest version of a user's custom data, call
:js-sdk:`User.refreshCustomData() <Realm.User.html#refreshCustomData>`.

.. literalinclude:: /examples/generated/web/access-custom-user-data.snippet.refresh-custom-user-data.js
   :language: javascript

Output
~~~~~~

.. code-block:: json

   {
     "_id": "5f233a3ac49aca916792de1d",
     "description": "a test document for user test@example.com",
     "userID": "5f1f298f757611faec901d0f",
     "favoriteColor": "pink"
   }

.. _web-modify-custom-user-data:

Modify a User's Custom Data
---------------------------

.. include:: /includes/write-access-to-custom-data-note.rst

You can modify a user's custom data by updating the underlying document in your
app's custom data collection.

The following example updates the user's custom data to set the
``favoriteColor`` property to ``"purple"``:

.. literalinclude:: /examples/generated/web/access-custom-user-data.snippet.modify-custom-user-data.js
   :language: javascript

Output
~~~~~~

.. code-block:: console
   
   old favoriteColor: pink
   new favoriteColor: purple

Summary
-------

- You can use custom user data to store information about your application users. 
- The custom user data field of the user object is read-only, and can only be modified to by performing CRUD operations through the Atlas service.