Lightweight dependency-free collection of React hooks for Firebase.
npm install react-firehooksor
yarn add react-firehooksIf you are using Firebase 8 or earlier, please use react-firebase-hooks.
If you previously used react-firebase-hooks or react-firebase9-hooks and want to migrate to react-firehooks, please read this migration document to learn what has changed and how your code needs to be adjusted.
This library consists of 4 modules with many hooks:
All hooks can be imported from react-firehooks directly or via react-firehooks/<module> to improve tree-shaking and bundle size.
import { ... } from 'react-firehooks/auth';Returns and updates the currently authenticated user
const [user, loading, error] = useAuthState(auth);Params:
auth: Firebase Auth instance
Params:
value: User;undefinedif user is currently being fetched, or an error occurredloading:truewhile fetching the user;falseif the user was fetched successfully or an error occurrederror:undefinedif no error occurred
import { ... } from 'react-firehooks/database';Returns and updates the DataSnapshot of the Realtime Database query
const [dataSnap, loading, error] = useObject(query);Params:
query: Realtime Database query
Returns:
value: DataSnapshot;undefinedif query is currently being fetched, or an error occurredloading:truewhile fetching the query;falseif the query was fetched successfully or an error occurrederror:undefinedif no error occurred
Returns the DataSnapshot of the Realtime Database query. Does not update the DataSnapshot once initially fetched
const [dataSnap, loading, error] = useObjectOnce(query);Params:
query: Realtime Database query
Returns:
value: DataSnapshot;undefinedif query is currently being fetched, or an error occurredloading:truewhile fetching the query;falseif the query was fetched successfully or an error occurrederror:undefinedif no error occurred
Returns and updates the DataSnapshot of the Realtime Database query
const [objectValue, loading, error] = useObjectValue(query, options);Params:
query: Realtime Database queryoptions: Options to configure how the object is fetchedconverter: Function to extract the desired data from the DataSnapshot. Similar to Firestore converters. Default:snap.val().
Returns:
value: Object value;undefinedif query is currently being fetched, or an error occurredloading:truewhile fetching the query;falseif the query was fetched successfully or an error occurrederror:undefinedif no error occurred
Returns the DataSnapshot of the Realtime Database query. Does not update the DataSnapshot once initially fetched
const [objectValue, loading, error] = useObjectValueOnce(query, options);Params:
query: Realtime Database queryoptions: Options to configure how the object is fetchedconverter: Function to extract the desired data from the DataSnapshot. Similar to Firestore converters. Default:snap.val().
Returns:
value: Object value;undefinedif query is currently being fetched, or an error occurredloading:truewhile fetching the query;falseif the query was fetched successfully or an error occurrederror:undefinedif no error occurred
import { ... } from 'react-firehooks/firestore';Returns and updates a QuerySnapshot of a Firestore Query
const [querySnap, loading, error] = useCollection(query, options);Params:
query: Firestore query that will be subscribed tooptions: Options to configure the subscription
Returns:
value: QuerySnapshot;undefinedif query is currently being fetched, or an error occurredloading:truewhile fetching the query;falseif the query was fetched successfully or an error occurrederror:undefinedif no error occurred
Returns and updates a the document data of a Firestore Query
const [data, loading, error] = useCollectionData(query, options);Params:
query: Firestore query that will be subscribed tooptions: Options to configure the subscription
Returns:
value: Query data;undefinedif query is currently being fetched, or an error occurredloading:truewhile fetching the query;falseif the query was fetched successfully or an error occurrederror:undefinedif no error occurred
Returns the data of a Firestore Query. Does not update the data once initially fetched
const [data, loading, error] = useCollectionDataOnce(query, options);Params:
query: Firestore query that will be fetchedoptions: Options to configure how the query is fetched
Returns:
value: Query data;undefinedif query is currently being fetched, or an error occurredloading:truewhile fetching the query;falseif the query was fetched successfully or an error occurrederror:undefinedif no error occurred
Returns the QuerySnapshot of a Firestore Query. Does not update the QuerySnapshot once initially fetched
const [querySnap, loading, error] = useCollectionOnce(query, options);Params:
query: Firestore query that will be fetchedoptions: Options to configure how the query is fetched
Returns:
value: QuerySnapshot;undefinedif query is currently being fetched, or an error occurredloading:truewhile fetching the query;falseif the query was fetched successfully or an error occurrederror:undefinedif no error occurred
Returns and updates a DocumentSnapshot of a Firestore DocumentReference
const [documentSnap, loading, error] = useDocument(documentReference, options);Params:
query: Firestore DocumentReference that will be subscribed tooptions: Options to configure the subscription
Returns:
value: DocumentSnapshot;undefinedif document does not exist, is currently being fetched, or an error occurredloading:truewhile fetching the document;falseif the document was fetched successfully or an error occurrederror:undefinedif no error occurred
Returns and updates the data of a Firestore DocumentReference
const [data, loading, error] = useDocumentData(documentReference, options);Params:
query: Firestore DocumentReference that will subscribed tooptions: Options to configure the subscription
Returns:
value: Document data;undefinedif document does not exist, is currently being fetched, or an error occurredloading:truewhile fetching the document;falseif the document was fetched successfully or an error occurrederror:undefinedif no error occurred
Returns the data of a Firestore DocumentReference
const [documentSnap, loading, error] = useDocumentDataOnce(documentReference, options);Params:
query: Firestore DocumentReference that will be fetchedoptions: Options to configure the document will be fetched
Returns:
value: Document data;undefinedif document does not exist, is currently being fetched, or an error occurredloading:truewhile fetching the document;falseif the document was fetched successfully or an error occurrederror:undefinedif no error occurred
Returns the DocumentSnapshot of a Firestore DocumentReference. Does not update the DocumentSnapshot once initially fetched
const [querySnap, loading, error] = useDocumentData(documentReference, options);Params:
query: Firestore DocumentReference that will be fetchedoptions: Options to configure how the document will be fetched
Returns:
value: DocumentSnapshot;undefinedif document does not exist, is currently being fetched, or an error occurredloading:truewhile fetching the document;falseif the document was fetched successfully or an error occurrederror:undefinedif no error occurred
import { ... } from 'react-firehooks/messaging';Returns the messaging token. The token never updates.
const [token, loading, error] = useMessagingToken(messaging, options);Params:
messaging: Firestore Messaging instanceoptions: Options to configure how the token will be fetched
Returns:
value: Messaging token;undefinedif token is currently being fetched, or an error occurredloading:truewhile fetching the token;falseif the token was fetched successfully or an error occurrederror:undefinedif no error occurred
import { ... } from 'react-firehooks/storage';Returns the data of a Google Cloud Storage object as a Blob
This hook is not available in Node.
const [data, loading, error] = useNode(storageReference);Params:
reference: Reference to a Google Cloud Storage objectmaxDownloadSizeBytes: If set, the maximum allowed size in bytes to retrieve.
Returns:
value: Object data as a Blob;undefinedif data of the object is currently being downloaded, or an error occurredloading:truewhile downloading the data of the object;falseif the data was downloaded successfully or an error occurrederror:undefinedif no error occurred
Returns the data of a Google Cloud Storage object
const [data, loading, error] = useBytes(storageReference);Params:
reference: Reference to a Google Cloud Storage objectmaxDownloadSizeBytes: If set, the maximum allowed size in bytes to retrieve.
Returns:
value: Object data;undefinedif data of the object is currently being downloaded, or an error occurredloading:truewhile downloading the data of the object;falseif the data was downloaded successfully or an error occurrederror:undefinedif no error occurred
Returns the download URL of a Google Cloud Storage object
const [url, loading, error] = useDownloadURL(storageReference);Params:
reference: Reference to a Google Cloud Storage object
Returns:
value: Download URL;undefinedif download URL is currently being fetched, or an error occurredloading:truewhile fetching the download URL;falseif the download URL was fetched successfully or an error occurrederror:undefinedif no error occurred
Returns the metadata of a Google Cloud Storage object
const [metadata, loading, error] = useMetadata(storageReference);Params:
reference: Reference to a Google Cloud Storage object
Returns:
value: Metadata;undefinedif metadata is currently being fetched, or an error occurredloading:truewhile fetching the metadata;falseif the metadata was fetched successfully or an error occurrederror:undefinedif no error occurred
Returns the data of a Google Cloud Storage object as a stream
This hook is only available in Node.
const [data, loading, error] = useNode(storageReference);Params:
reference: Reference to a Google Cloud Storage objectmaxDownloadSizeBytes: If set, the maximum allowed size in bytes to retrieve.
Returns:
value: Object data as a stream;undefinedif data of the object is currently being downloaded, or an error occurredloading:truewhile downloading the data of the object;falseif the data was downloaded successfully or an error occurrederror:undefinedif no error occurred
To build the library, first install the dependencies, then run npm run build.
npm install
npm run buildTo run the tests, first install the dependencies, then run npm test. Watch mode can be started with npm test -- --watch.
npm install
npm testThis library is heavily inspired by react-firebase-hooks. It was created because react-firebase-hooks seemed unmaintained and did not support Firebase v9 for a couple of months. react-firehooks is not a fork but a completely new code base exporting almost identical hooks.