AppProvider (@realm/react)

Realm is now Atlas Device SDK – Learn More

Type signature

AppProvider(props, context?): null | ReactElement<any, any>

Components nested within AppProvider can access your App Services App and use the AppProvider hooks.

Props

All properties of AppConfiguration can be passed as props to AppProvider.

Configure AppProvider

To set up your App client, pass the App ID string to the id prop of the AppProvider. Wrap any components that need to access the App with AppProvider.

import React from 'react';
import {AppProvider} from '@realm/react';
function AppWrapper() {
  return (
    <View>
      <AppProvider id={APP_ID}>
        <MyApp />
      </AppProvider>
    </View>
  );
}

You can create multiple App client instances to connect to multiple Apps. All App client instances that share the same App ID use the same underlying connection.

Important

Changing an App Config After Initializing the App

Changed in version realm@12.6.0: baseUrl is not cached

When you initialize the App client, the configuration is cached internally. Attempting to "close" and then re-open an App with a changed configuration within the same process has no effect. The client continues to use the cached configuration.

Starting with React Native SDK version 12.6.0, the baseUrl in the AppConfiguration is not cached. This means that you can change the baseUrl and the App client will use the updated configuration. In earlier SDK versions, changes to the baseUrl in a cached App configuration have no effect.

Hooks Used with AppProvider

useAuth()

Type signature

useAuth(): UseAuth

useAuth has an authentication method for every App Services authentication provider.

result

Type signature

result: AuthResult

Result of authentication hook operation. For example, result.operation gives you the name of the current operation.

Enum values

state. Can be "not-started", "pending", "success", "error".
operation. For a list of all operation names, refer to the API documentation.
pending. Can be true or false.
success. Can be true or false.
error. Error-based object or undefined.

logIn(credentials)

Type signature

logIn(credentials: Realm.Credentials): void

Parameters

credentials. A Realm credential supplied by any supported Realm authentication.

Example

Logs in a user with any authentication mechanism supported by Realm. If called when a user is logged in, the current user switches to the new user. Usually, it's better to use the more specific login methods.

const {logIn, result} = useAuth();
useEffect(() => logIn(Realm.Credentials.anonymous()), []);
if(result.pending) {
  return (<LoadingSpinner/>)
}
if(result.error) {
  return (<ErrorComponent/>)
}
if(result.success) {
  return (<SuccessComponent/>)
}
//...

logInWithAnonymous()

Type signature

logInWithAnonymous(): void

Example

const {logInWithAnonymous, result} = useAuth();
const performLogin = () => {
   logInWithAnonymous();
};

logInWithApiKey(key)

Type signature

logInWithApiKey(key: string): void

Parameters

key. A string that is linked to an App Services user.

Example

const {logInWithApiKey, result} = useAuth();
const performLogin = () => {
const key = getApiKey(); // user defined function
   logInWithApiKey(key);
};

logInWithEmailPassword(credentials)

Type signature

logInWithEmailPassword(credentials: {
  email: string;
  password: string;
}): void

Parameters

credentials. An object with email and password fields.

Example

const {logInWithEmailPassword, result} = useAuth();
const [email, setEmail] = useState('');
const [password, setPassword] = useState('');
const performLogin = () => {
   logInWithEmailPassword({email, password});
};

logInWithJWT(credentials)

Type signature

logInWithJWT(token: string): void

Parameters

credentials. A string representation of a user's JWT.

Example

const {logInWithJWT, result} = useAuth();
const performLogin = () => {
const token = authorizeWithCustomerProvider(); // user defined function
   logInWithJWT(token);
};

logInWithGoogle(credentials)

Type signature

logInWithGoogle(credentials: {
     idToken: string;
 } | {
     authCode: string;
 }): void;

Parameters

credentials. An object with an idToken or authCode field that should contain the string token you get from Google Identity Services.

Example

const {logInWithGoogle, result} = useAuth();
const performLogin = () => {
const token = getGoogleToken(); // user defined function
   logInWithGoogle({idToken: token});
};

logInWithApple(idToken)

Type signature

logInWithApple(idToken: string): void;

Parameters

idToken. A string you get from the Apple SDK.

Example

const {logInWithApple, result} = useAuth();
const performLogin = () => {
const token = getAppleToken(); // user defined function
   logInWithApple(token);
};

logInWithFacebook(accessToken)

Type signature

logInWithFacebook(accessToken: string): void;

Parameters

accessToken. A string you get from the Facebook SDK.

Example

const {logInWithFacebook, result} = useAuth();
const performLogin = () => {
const token = getFacebookToken(); // user defined function
   logInWithFacebook(token);
};

logInWithFunction(payload)

Type signature

logInWithFunction<PayloadType extends Record<string, unknown>>(payload: PayloadType): void;

Parameters

payload. An object that contains user information you want to pass to the App Services function that processes log in requests.

Example

const {logInWithFunction, result} = useAuth();
const performLogin = () => {
const customPayload = getAuthParams(); // user defined arguments
   logInWithFunction(customPayload);
};

logOut()

Type signature

logOut(): void;

Example

Logs out the current user.

const {logOut, result} = useEmailPasswordAuth();
const performLogout = () => {
   logOut();
}

useEmailPasswordAuth()

Type signature

result: AuthResult

Result of authentication hook operation. For example, result.operation gives you the name of the current operation.

Enum values

state. Can be "not-started", "pending", "success", "error".
operation. For a list of all operation names, refer to the API documentation.
pending. Can be true or false.
success. Can be true or false.
error. Error-based object or undefined.

logIn(credentials)

Type signature

logIn(credentials: { email: string; password: string }): void;

Parameters

credentials. An object that contains email and password properties.

Example

Logs a user in using an email and password. You could also call logIn(Realm.Credentials.emailPassword(email, password)). Returns a Realm.User instance of the logged-in user.

const {logIn, result} = useEmailPasswordAuth();
const [email, setEmail] = useState('');
const [password, setPassword] = useState('');
const performLogin = () => {
   logIn({email, password});
};
if(result.pending) {
   return (<LoadingSpinner/>)
}
if(result.error) {
   return (<ErrorComponent/>)
}
if(result.success) {
   return (<SuccessComponent/>)
}
//...

logOut()

Type signature

logOut(): void;

Example

Logs out the current user.

const {logOut, result} = useEmailPasswordAuth();
const performLogout = () => {
   logOut();
}

register(args)

Type signature

register(args: { email: string; password: string }): void;

Parameters

args. An object that contains email and password properties.

Example

Registers a new user. Requires a user email and password.

const {register, result} = useEmailPasswordAuth();
const [email, setEmail] = useState('');
const [password, setPassword] = useState('');
const performRegister = () => {
   register({email, password});
};

confirm(args)

Type signature

confirm(args: { token: string; tokenId: string }): void;

Parameters

args. An object that contains token and tokenId properties.

Example

Confirms a user account. Requires a token and tokenId.

const {confirm, result} = useEmailPasswordAuth();
const performConfirmation = () => {
   confirm({token, tokenId});
};

resendConfirmationEmail(args)

Type signature

resendConfirmationEmail(args: { email: string }): void;

Parameters

args. An object that contains an email property.

Example

Resends a confirmation email.

const {resendConfirmationEmail, result} = useEmailPasswordAuth();
const [email, setEmail] = useState('');
const performResendConfirmationEmail = () => {
   resendConfirmationEmail({email});
};

retryCustomConfirmation(args)

Type signature

retryCustomConfirmation(args: { email: string }): void;

Parameters

args. An object that contains an email property.

Example

Retries confirmation with a custom function.

const {retryCustomConfirmation, result} = useEmailPasswordAuth();
const [email, setEmail] = useState('');
const performRetryCustomConfirmation = () => {
   retryCustomConfirmation({email});
};

sendResetPasswordEmail(args)

Type signature

sendResetPasswordEmail(args: { email: string }): void;

Parameters

args. An object that contains an email property.

Example

Sends a password reset email.

const {sendResetPasswordEmail, result} = useEmailPasswordAuth();
const [email, setEmail] = useState('');
const performSendResetPasswordEmail = () => {
   sendResetPasswordEmail({email});
};

resetPassword(args)

Type signature

resetPassword(args: { token: string; tokenId: string; password: string }): void;

Parameters

args. An object that contains token, tokenId, and password properties.

Example

Resets a user's password.

const {resetPassword, result} = useEmailPasswordAuth();
const [password, setPassword] = useState('');
const performResetPassword = () => {
   resetPassword({token, tokenId, password});
};

callResetPasswordFunction(args, restArgs)

Type signature

callResetPasswordFunction<Args extends unknown[] = []>(
 args: {
   email: string;
   password: string;
 },
 ...restArgs: Args
): void;

Parameters

args. An object that contains email and password properties.
restArgs. Additional arguments that you need to pass to your custom reset password function.

Example

Calls your App Services backend password reset function. Can pass arguments to the function as needed.

const {callResetPasswordFunction, result} = useEmailPasswordAuth();
const [email, setEmail] = useState('');
const [password, setPassword] = useState('');
const performResetPassword = () => {
   callResetPasswordFunction({email, password}, "extraArg1", "extraArg2");
};

useApp()

Type signature

useApp<FunctionsFactoryType, CustomDataType>(): Realm.App<FunctionsFactoryType, CustomDataType>

Example

The useApp() hook provides access to a Realm.App instance.

import React from 'react';
import {useApp} from '@realm/react';

function MyApp() {
  const app = useApp();
  // Proceed to app logic...
}

Returns

Realm.App An instance of the current Realm.App created by AppProvider.

←

→

AppProvider (@realm/react).leafygreen-ui-m0pgrr{-webkit-align-self:center;-ms-flex-item-align:center;align-self:center;padding:0 10px;visibility:hidden;}.leafygreen-ui-a30zj9{color:#889397;vertical-align:middle;margin-top:-2px;}.css-1l4s55v{margin-top:-175px;position:absolute;padding-bottom:2px;}

Props

Configure AppProvider

Important

Changing an App Config After Initializing the App

Hooks Used with AppProvider

useAuth()

result

logIn(credentials)

logInWithAnonymous()

logInWithApiKey(key)

logInWithEmailPassword(credentials)

logInWithJWT(credentials)

logInWithGoogle(credentials)

logInWithApple(idToken)

logInWithFacebook(accessToken)

logInWithFunction(payload)

logOut()

useEmailPasswordAuth()

logIn(credentials)

logOut()

register(args)

confirm(args)

resendConfirmationEmail(args)

retryCustomConfirmation(args)

sendResetPasswordEmail(args)

resetPassword(args)

callResetPasswordFunction(args, restArgs)

useApp()

AppProvider (@realm/react)