Providers & Hooks
On this page
The @realm/react library offers custom React components that eliminate the boilerplate needed to
develop a React app. The components leverage the Provider design pattern to manage user
creation, user authentication, and data management.
RealmProvider: Work with the configured database.AppProvider: Connect to your App Client for user authentication, only necessary when using Device Sync.UserProvider: Access to the logged-in user object, only necessary when using Device Sync.
The Providers are available to all frameworks used to build with the JavaScript SDK.
Getting Started with Providers
Like all React components, you call Providers using html opening and closing tags. Nesting a component within in another component's tags creates a parent-child relationship between them, where child components can access the context created by its parent component.
Props
Components take parameters called Props as input, passed into the opening tag. The props passed into a parent component help create the context inherited by the components it wraps. Each Provider has different props you can use for configuration.
Configure your Providers
This section details how to configure and expose a single realm using a RealmProvider
imported directly from @realm/react. For information about using createRealmContext()
to configure a realm or exposing more than one realm, refer to their respective sections below.
Working with Providers using Hooks
To use the Provider's context in your app's components, you can use .
Hooks act as functions used to access states in your app. React offers built-in hooks you can use either on their own or to build custom hooks.
There are two important rules to consider when working with hooks:
Hooks can only be used at the top level of a React component.
Hooks can only be called in a React component or a custom hook, not in regular JavaScript functions.
The @realm/react library has custom hooks for each Provider you can import and
use in any wrapped component.
Create Context with createRealmContext()
createRealmContext(realmConfig?): RealmContext
Most of the time, you will only use createRealmContext() if you need to
configure more than one realm. Otherwise, you should import RealmProvider
and hooks directly from @realm/react.
The createRealmContext() method creates a React Context object for a realm with a given
Configuration. The
Context object contains the following:
A Context Provider (referred to as
RealmProviderelsewhere) component that wraps around child components and provides them with access to hooks.Various prebuilt Hooks that access the configured realm.
For a detailed guide, refer to Expose More Than One Realm.
Parameters
realmConfig?: Realm.ConfigurationAll properties of BaseConfiguration can be used.
Returns
RealmContextAn object containing a
RealmProvidercomponent, and theuseRealm,useQueryanduseObjecthooks.
Configure More Than One Realm
When you import RealmProvider from @realm/react, that Provider has a
specific context and is associated with a single realm. If you need to configure
more than one realm, use createRealmContext() to instantiate a new Provider
for each realm.
If you import useRealm(), useQuery(), or useObject() directly from
@realm/react, those hooks use the default realm context. To work with more
than one realm, you need to destructure a new realm Provider and its associated
hooks from the result of createRealmContext(). You should namespace providers
to avoid confusion about which Provider and hooks you're working with.
For a detailed guide, refer to Expose More Than One Realm.
For details about createRealmContext(), refer to "Create Context with
createRealmContext()" on this page.