README
React Firehooks 🔥🪝
Lightweight dependency-free collection of React hooks for Firebase.
Installation
npm install react-firehooks
or
yarn add react-firehooks
Compatibility
If you are using Firebase 8 or earlier, please use react-firebase-hooks
.
Migrate from 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.
Usage
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.
Auth
import { ... } from 'react-firehooks/auth';
useAuthState
Returns and updates the currently authenticated user
const [user, loading, error] = useAuthState(auth);
Params:
auth
: Firebase Auth instance
Params:
value
: User;undefined
if user is currently being fetched, or an error occurredloading
:true
while fetching the user;false
if the user was fetched successfully or an error occurrederror
:undefined
if no error occurred
Database
import { ... } from 'react-firehooks/database';
useObject
Returns and updates the DataSnapshot of the Realtime Database query
const [dataSnap, loading, error] = useObject(query);
Params:
query
: Realtime Database query
Returns:
value
: DataSnapshot;undefined
if query is currently being fetched, or an error occurredloading
:true
while fetching the query;false
if the query was fetched successfully or an error occurrederror
:undefined
if no error occurred
useObjectOnce
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;undefined
if query is currently being fetched, or an error occurredloading
:true
while fetching the query;false
if the query was fetched successfully or an error occurrederror
:undefined
if no error occurred
useObjectValue
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;undefined
if query is currently being fetched, or an error occurredloading
:true
while fetching the query;false
if the query was fetched successfully or an error occurrederror
:undefined
if no error occurred
useObjectValueOnce
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;undefined
if query is currently being fetched, or an error occurredloading
:true
while fetching the query;false
if the query was fetched successfully or an error occurrederror
:undefined
if no error occurred
Firestore
import { ... } from 'react-firehooks/firestore';
useCollection
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;undefined
if query is currently being fetched, or an error occurredloading
:true
while fetching the query;false
if the query was fetched successfully or an error occurrederror
:undefined
if no error occurred
useCollectionData
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;undefined
if query is currently being fetched, or an error occurredloading
:true
while fetching the query;false
if the query was fetched successfully or an error occurrederror
:undefined
if no error occurred
useCollectionDataOnce
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;undefined
if query is currently being fetched, or an error occurredloading
:true
while fetching the query;false
if the query was fetched successfully or an error occurrederror
:undefined
if no error occurred
useCollectionOnce
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;undefined
if query is currently being fetched, or an error occurredloading
:true
while fetching the query;false
if the query was fetched successfully or an error occurrederror
:undefined
if no error occurred
useDocument
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;undefined
if document does not exist, is currently being fetched, or an error occurredloading
:true
while fetching the document;false
if the document was fetched successfully or an error occurrederror
:undefined
if no error occurred
useDocumentData
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;undefined
if document does not exist, is currently being fetched, or an error occurredloading
:true
while fetching the document;false
if the document was fetched successfully or an error occurrederror
:undefined
if no error occurred
useDocumentDataOnce
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;undefined
if document does not exist, is currently being fetched, or an error occurredloading
:true
while fetching the document;false
if the document was fetched successfully or an error occurrederror
:undefined
if no error occurred
useDocumentOnce
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;undefined
if document does not exist, is currently being fetched, or an error occurredloading
:true
while fetching the document;false
if the document was fetched successfully or an error occurrederror
:undefined
if no error occurred
Messaging
import { ... } from 'react-firehooks/messaging';
useMessagingToken
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;undefined
if token is currently being fetched, or an error occurredloading
:true
while fetching the token;false
if the token was fetched successfully or an error occurrederror
:undefined
if no error occurred
Storage
import { ... } from 'react-firehooks/storage';
useBlob
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;undefined
if data of the object is currently being downloaded, or an error occurredloading
:true
while downloading the data of the object;false
if the data was downloaded successfully or an error occurrederror
:undefined
if no error occurred
useBytes
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;undefined
if data of the object is currently being downloaded, or an error occurredloading
:true
while downloading the data of the object;false
if the data was downloaded successfully or an error occurrederror
:undefined
if no error occurred
useDownloadURL
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;undefined
if download URL is currently being fetched, or an error occurredloading
:true
while fetching the download URL;false
if the download URL was fetched successfully or an error occurrederror
:undefined
if no error occurred
useMetadata
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;undefined
if metadata is currently being fetched, or an error occurredloading
:true
while fetching the metadata;false
if the metadata was fetched successfully or an error occurrederror
:undefined
if no error occurred
useStream
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;undefined
if data of the object is currently being downloaded, or an error occurredloading
:true
while downloading the data of the object;false
if the data was downloaded successfully or an error occurrederror
:undefined
if no error occurred
Development
Build
To build the library, first install the dependencies, then run npm run build
.
npm install
npm run build
Tests
To run the tests, first install the dependencies, then run npm test
. Watch mode can be started with npm test -- --watch
.
npm install
npm test
Resources
React Firebase Hooks
This 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.