Providers & Hooks

useRealm()

useRealm(): Realm

The useRealm() Hook returns an opened database instance. The database instance gives you access to database methods and properties. For example, you can call realm.write() to add a Realm Object to your database.

To learn more about modifying data in your database, refer to Write Transactions.

const CreatePersonInput = () => {
  const [name, setName] = useState('');
  const realm = useRealm();
  const handleAddPerson = () => {
    realm.write(() => {
      realm.create('Person', {_id: PERSON_ID, name: name, age: 25});
    });
  };
  return (
    <>
      <TextInput value={name} onChangeText={setName}  />
      <Button
        onPress={() => handleAddPerson()}
        title='Add Person'
      />
    </>
  );
};

Returns

• Realm Returns a database instance from the RealmProvider context.

useObject()

useObject<T>(type, sdks-open-synced-database-offlineKey): T & Realm.Object<T> | null

The useObject() Hook returns a Realm Object for a given primary key. You can pass an object class or the class name as a string and the primary key.

The useObject() Hook returns null if the object doesn't exist or you have deleted it. The Hook will automatically subscribe to updates and rerender the component using the Hook on any change to the object.

const TaskItem = ({_id}: {_id: number}) => {
  const myTask = useObject(Task, _id);
  return (
    <View>
      {myTask ? (
        <Text>
          {myTask.name} is a task with the priority of: {myTask.priority}
        </Text>
      ) : null}
    </View>
  );
};

Parameters

• type: string A string that matches your object model's class name or a reference to a class that extends Realm.Object.

• primaryKey: T[keyof T] The primary key of the desired object.

Returns

• Realm.Object | null A Realm Object or null if no object is found.

useQuery()

useQuery<T>(type, query?, deps?): Realm.Results<T & Realm.Object<T>>

The useQuery() Hook returns a result that is a collection of Realm Objects of a given type. These are the results of your query. A query can be an object class or the class name as a string.

The useQuery() method subscribes to updates to any objects in the collection and rerenders the component using it on any change to the results.

You can use .filtered() and .sorted() to filter and sort your query results. Do this in the query argument of useQuery so that they only run when there are changes in the dependency array. For more examples, refer to the Read Objects page.

const TaskList = () => {
  const [priority, setPriority] = useState(4);
  // filter for tasks with a high priority
  const highPriorityTasks = useQuery(
    Task,
    tasks => {
      return tasks.filtered('priority >= $0', priority);
    },
    [priority],
  );
  // filter for tasks that have just-started or short-running progress
  const lowProgressTasks = useQuery(Task, tasks => {
    return tasks.filtered(
      '$0 <= progressMinutes && progressMinutes < $1',
      1,
      10,
    );
  });
  return (
    <>
      <Text>Your high priority tasks:</Text>
      {highPriorityTasks.map(taskItem => {
        return <Text>{taskItem.name}</Text>;
      })}
      <Text>Your tasks without much progress:</Text>
      {lowProgressTasks.map(taskItem => {
        return <Text>{taskItem.name}</Text>;
      })}
    </>
  );
};

Parameters

• type: string A string that matches your object model's class name or a reference to a class that extends Realm.Object.

• query?: QueryCallback<T> A query function that can filter and sort query results. Builds on useCallback to memoize the query function.

• deps?: DependencyList A list of query function dependencies that's used to memoize the query function.

Returns

• Realm.Results<T> A Realm Object or null if no object is found.

useUser()

useUser<FunctionsFactoryType, CustomDataType, UserProfileDataType>(): Realm.User<FunctionsFactoryType, CustomDataType, UserProfileDataType>

The useUser() Hook provides access to the logged-in user. For example, you can use useUser() to log the current user out.

When changes to the user object happen, this Hook will rerender its parent component. For example, if you call user.refreshCustomData to get updated custom user data, the useUser() parent component will rerender.

function UserInformation() {
  const user = useUser();
  const {logOut} = useAuth();
  const performLogout = () => {
    logOut();
  };
  // Add UI for logging out...
}

Returns

• Realm.User An instance of the currently-authenticated Atlas user.

useApp()

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.

useAuth()

useAuth(): UseAuth

You destructure the useAuth() Hook result into a result and authentication method.

result: AuthResult

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

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

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

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

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

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

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

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

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

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

useEmailPasswordAuth()

You destructure the useEmailPasswordAuth() Hook result into a result and authentication operation.

result: AuthResult

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/>)
}
//...

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

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

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

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

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

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

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

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