reactfire/docs/reference.md

Reference Docs

Table of Contents

• Hooks

  • SDK

    • useFirebaseApp
    • useAnalytics
    • useAuth
    • useDatabase
    • useFirestore
    • useFunctions
    • useMessaging
    • usePerformance
    • useRemoteConfig
    • useStorage

  • Authentication

    • useUser

  • Database

    • Cloud Firestore
      • useFirestoreDoc
      • useFirestoreDocOnce
      • useFirestoreDocData
      • useFirestoreDocDataOnce
      • useFirestoreCollection
      • useFirestoreCollectionData
    • Realtime Database
      • useDatabaseObject
      • useDatabaseObjectData
      • useDatabaseList
      • useDatabaseListData

  • Cloud Storage

    • useStorageTask
    • useStorageDownloadURL

  • useObservable

  • ReactFireOptions

• Components

  • FirebaseAppProvider
  • Performance Monitoring
    • SuspenseWithPerf
  • Authentication
    • AuthCheck
  • Cloud Storage
    • StorageImage

• Preloading

  • SDK
    • preloadAnalytics
    • preloadAuth
    • preloadDatabase
    • preloadFirestore
    • preloadFunctions
    • preloadMessaging
    • preloadPerformance
    • preloadRemoteConfig
    • preloadStorage
  • Data
    • preloadFirestoreDoc

Hooks

useFirebaseApp

When called from a component nested inside a FirebaseAppProvider, useFirebaseApp returns the root Firebase object.

IMPORTANT: By default, useFirebaseApp returns a firebase object without any products attached to it (e.g. you can't call firebase.firestore(). To do that, you need to import a Firebase feature (import 'firebase/firestore') or lazy load a feature with one of the Hooks below)

Returns

firebase

useAnalytics

Throws a Promise by default

Returns firebase.analytics When called from a component nested inside a FirebaseAppProvider. If firebase.analytics doesn't exist, it lazy loads the Analytics SDK.

Returns

firebase.analytics

useAuth

Throws a Promise by default

Returns firebase.auth When called from a component nested inside a FirebaseAppProvider. If firebase.auth doesn't exist, it lazy loads the Auth SDK.

Returns

firebase.auth

useDatabase

Throws a Promise by default

Returns firebase.database When called from a component nested inside a FirebaseAppProvider. If firebase.database doesn't exist, it lazy loads the Realtime Database SDK.

Returns

firebase.database

useFirestore

Throws a Promise by default

Returns firebase.firestore When called from a component nested inside a FirebaseAppProvider. If firebase.firestore doesn't exist, it lazy loads the Cloud Firestore SDK.

Returns

firebase.firestore

useFunctions

Throws a Promise by default

Returns firebase.functions When called from a component nested inside a FirebaseAppProvider. If firebase.functions doesn't exist, it lazy loads the Cloud Functions for Firebase SDK.

Returns

firebase.functions

useMessaging

Throws a Promise by default

Returns firebase.messaging When called from a component nested inside a FirebaseAppProvider. If firebase.messaging doesn't exist, it lazy loads the Firebase Cloud Messaging SDK.

Returns

firebase.messaging

usePerformance

Throws a Promise by default

Returns firebase.performance When called from a component nested inside a FirebaseAppProvider. If firebase.performance doesn't exist, it lazy loads the Performance Monitoring SDK.

Returns

firebase.performance

useRemoteConfig

Throws a Promise by default

Returns firebase.remoteConfig When called from a component nested inside a FirebaseAppProvider. If firebase.remoteConfig doesn't exist, it lazy loads the Remote Config SDK.

Returns

firebase.remoteConfig

useStorage

Throws a Promise by default

Returns firebase.storage When called from a component nested inside a FirebaseAppProvider. If firebase.storage doesn't exist, it lazy loads the Storage SDK.

Returns

firebase.storage

useUser

Get the user that is currently signed in. Lazy loads the firebase/auth SDK if it is not already loaded.

Throws a Promise by default

Parameters

Parameter	Type	Description
auth ?	Auth	[optional] auth object. If not provided, useUser will use useFirebaseApp to find the Auth object.
options ?	ReactFireOptions	Options. This hook will not throw a Promise if you provide startWithValue.

Returns

User

useFirestoreDoc

Listen to a Firestore Document.

Throws a Promise by default

Parameters

Parameter	Type	Description
ref	DocumentReference	A reference to the document you want to listen to
options ?	ReactFireOptions	Options. This hook will not throw a Promise if you provide startWithValue.

Returns

DocumentSnapshot

useFirestoreDocOnce

Get a firestore document, but don't listen for updates.

Throws a Promise by default

Parameters

Parameter	Type	Description
ref	DocumentReference	A reference to the document you want to listen to
options ?	ReactFireOptions	Options. This hook will not throw a Promise if you provide startWithValue.

Returns

DocumentSnapshot

useFirestoreDocData

Listen to a Firestore Document.

Throws a Promise by default

Parameters

Parameter	Type	Description
ref	DocumentReference	A reference to the document you want to listen to
options ?	ReactFireOptions	Options. This hook will not throw a Promise if you provide startWithValue.

Returns

T

useFirestoreDocDataOnce

Get a firestore document, but don't listen for updates.

Throws a Promise by default

Parameters

Parameter	Type	Description
ref	DocumentReference	A reference to the document you want to listen to
options ?	ReactFireOptions	Options. This hook will not throw a Promise if you provide startWithValue.

Returns

T

useFirestoreCollection

Listen to a Firestore Collection.

Throws a Promise by default

Parameters

Parameter	Type	Description
ref	Query	A query for the collection you want to listen to
options ?	ReactFireOptions	Options. This hook will not throw a Promise if you provide startWithValue.

Returns

QuerySnapshot

useFirestoreCollectionData

Listen to a Firestore Collection.

Throws a Promise by default

Parameters

Parameter	Type	Description
ref	Query	A query for the collection you want to listen to
options ?	ReactFireOptions	Options. This hook will not throw a Promise if you provide startWithValue.

Returns

T[]

useDatabaseObject

Listen to a Realtime Database Object.

Throws a Promise by default

Parameters

Parameter	Type	Description
ref	Reference	A reference to the object you want to listen to
options ?	ReactFireOptions	Options. This hook will not throw a Promise if you provide startWithValue.

Returns

QueryChange

useDatabaseObjectData

Listen to a Realtime Database Object.

Throws a Promise by default

Parameters

Parameter	Type	Description
ref	Reference	A reference to the object you want to listen to
options ?	ReactFireOptions	Options. This hook will not throw a Promise if you provide startWithValue.

Returns

T

useDatabaseList

Listen to a Realtime Database list.

Throws a Promise by default

Parameters

Parameter	Type	Description
ref	Reference	A reference to the list you want to listen to
options ?	ReactFireOptions	Options. This hook will not throw a Promise if you provide startWithValue.

Returns

QueryChange[]

useDatabaseListData

Listen to a Realtime Database list.

Throws a Promise by default

Parameters

Parameter	Type	Description
ref	Reference	A reference to the list you want to listen to
options ?	ReactFireOptions	Options. This hook will not throw a Promise if you provide startWithValue.

Returns

T[]

useStorageTask

Listen to a Storage UploadTask

Throws a Promise by default

Parameters

Parameter	Type	Description
task	UploadTask
ref	Reference
options ?	ReactFireOptions

Returns

UploadTaskSnapshot

useStorageDownloadURL

Subscribe to a storage blob's download URL

useobservable link

Throws a Promise by default

Parameters

Parameter	Type	Description
ref	Reference
options ?	ReactFireOptions

Returns

string

useObservable<T>

Throws a Promise by default

Parameter	Type	Description
source	Observable	The observable whose values you want to subscribe to
observableId	string	A unique id. If this id matches an observable already in the cache, useObservable will reuse that observable instead of the one passed in.
startWithValue ?	T	A value to emit first (if you don't want useObservable to throw a Promise)
deps	React.DependencyList	A list of values that, when changed, should cause useObservable to re-subscribe to its observable

Returns

T

ReactFireOptions

Property	Type
startWithValue	any

Components

FirebaseAppProvider

A React Context Provider that allows the useFirebaseApp hook to pick up the firebase object.

Sample usage

const firebaseConfig = {
  /* web app config from Firebase console */
};

<FirebaseAppProvider firebaseConfig={firebaseConfig} initPerformance>
  <App />
</FirebaseAppProvider>;

Props

Prop	Type	Description
config	Object	the web app config object usually passed to initializeApp
initPerformance	bool	Whether or not to initialize Firebase Performance Monitoring

AuthCheck

Renders children if a user is signed in and meets the required claims. Renders fallback otherwise.

Props

Property	Type
auth	Auth
children	React.Component
fallback	React.Component
requiredClaims	Object

StorageImage

Renders an image based on a Cloud Storage path.

Props

Property	Type
storagePath	string
storage?	firebase.storage.Storage

...and any other props a normal React <img> element can take.

SuspenseWithPerf

Starts a Firebase Performance Monitoring trace and ends it when suspense stops suspending.

Props

Property	Type
children	React.Component
fallback	React.Component
firePerf ?	any
traceId	string

Preloading

preloadAnalytics

Start importing the firebase/analytics package.

Parameters

Parameter	Type	Description
firebaseApp	firebase.app.App	The Firebase object

Returns

Promise<firebase.analytics>

preloadAuth

Start importing the firebase/auth package.

Parameters

Parameter	Type	Description
firebaseApp	firebase.app.App	The Firebase object

Returns

Promise<firebase.auth>

preloadDatabase

Start importing the firebase/database package.

Parameters

Parameter	Type	Description
firebaseApp	firebase.app.App	The Firebase object

Returns

Promise<firebase.database>

preloadFirestore

Start importing the firebase/firestore package.

Parameters

Parameter	Type	Description
firebaseApp	firebase.app.App	The Firebase object

Returns

Promise<firebase.firestore>

preloadFunctions

Start importing the firebase/functions package.

Parameters

Parameter	Type	Description
firebaseApp	firebase.app.App	The Firebase object

Returns

Promise<firebase.functions>

preloadMessaging

Start importing the firebase/messaging package.

Parameters

Parameter	Type	Description
firebaseApp	firebase.app.App	The Firebase object

Returns

Promise<firebase.messaging>

preloadPerformance

Start importing the firebase/performance package.

Parameters

Parameter	Type	Description
firebaseApp	firebase.app.App	The Firebase object

Returns

Promise<firebase.performance>

preloadRemoteConfig

Start importing the firebase/remoteConfig package.

Parameters

Parameter	Type	Description
firebaseApp	firebase.app.App	The Firebase object

Returns

Promise<firebase.remoteConfig>

preloadStorage

Start importing the firebase/storage package.

Parameters

Parameter	Type	Description
firebaseApp	firebase.app.App	The Firebase object

Returns

Promise<firebase.storage>

preloadFirestoreDoc

⚠️ experimental

Starts subscribing to a Firestore document in the background. Cleans itself up after 30 seconds if useFirestoreDoc calls are made.

Parameters

Parameter	Type	Description
refProvider	(firestore: firebase.firestore.Firestore) => firestore.DocumentReference	A function that is called when the firestore SDK is ready and generates a DocumentReference to read
firebaseApp	firebase.app.App	The firebase app

Returns

Promise<Obsevable<any>>