react-firehooks

Lightweight dependency-free collection of React hooks for Firebase

Usage no npm install needed!

<script type="module">
  import reactFirehooks from 'https://cdn.skypack.dev/react-firehooks';
</script>

README

npm downloads npm bundle size tests license semantic-release

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

Type Documentation

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 occurred
  • loading: true while fetching the user; false if the user was fetched successfully or an error occurred
  • error: 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 occurred
  • loading: true while fetching the query; false if the query was fetched successfully or an error occurred
  • error: 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 occurred
  • loading: true while fetching the query; false if the query was fetched successfully or an error occurred
  • error: 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 query
  • options: Options to configure how the object is fetched
    • converter: 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 occurred
  • loading: true while fetching the query; false if the query was fetched successfully or an error occurred
  • error: 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 query
  • options: Options to configure how the object is fetched
    • converter: 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 occurred
  • loading: true while fetching the query; false if the query was fetched successfully or an error occurred
  • error: 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 to
  • options: Options to configure the subscription

Returns:

  • value: QuerySnapshot; undefined if query is currently being fetched, or an error occurred
  • loading: true while fetching the query; false if the query was fetched successfully or an error occurred
  • error: 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 to
  • options: Options to configure the subscription

Returns:

  • value: Query data; undefined if query is currently being fetched, or an error occurred
  • loading: true while fetching the query; false if the query was fetched successfully or an error occurred
  • error: 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 fetched
  • options: Options to configure how the query is fetched

Returns:

  • value: Query data; undefined if query is currently being fetched, or an error occurred
  • loading: true while fetching the query; false if the query was fetched successfully or an error occurred
  • error: 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 fetched
  • options: Options to configure how the query is fetched

Returns:

  • value: QuerySnapshot; undefined if query is currently being fetched, or an error occurred
  • loading: true while fetching the query; false if the query was fetched successfully or an error occurred
  • error: 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 to
  • options: Options to configure the subscription

Returns:

  • value: DocumentSnapshot; undefined if document does not exist, is currently being fetched, or an error occurred
  • loading: true while fetching the document; false if the document was fetched successfully or an error occurred
  • error: 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 to
  • options: Options to configure the subscription

Returns:

  • value: Document data; undefined if document does not exist, is currently being fetched, or an error occurred
  • loading: true while fetching the document; false if the document was fetched successfully or an error occurred
  • error: 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 fetched
  • options: 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 occurred
  • loading: true while fetching the document; false if the document was fetched successfully or an error occurred
  • error: 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 fetched
  • options: 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 occurred
  • loading: true while fetching the document; false if the document was fetched successfully or an error occurred
  • error: 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 instance
  • options: Options to configure how the token will be fetched

Returns:

  • value: Messaging token; undefined if token is currently being fetched, or an error occurred
  • loading: true while fetching the token; false if the token was fetched successfully or an error occurred
  • error: 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 object
  • maxDownloadSizeBytes: 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 occurred
  • loading: true while downloading the data of the object; false if the data was downloaded successfully or an error occurred
  • error: 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 object
  • maxDownloadSizeBytes: 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 occurred
  • loading: true while downloading the data of the object; false if the data was downloaded successfully or an error occurred
  • error: 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 occurred
  • loading: true while fetching the download URL; false if the download URL was fetched successfully or an error occurred
  • error: 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 occurred
  • loading: true while fetching the metadata; false if the metadata was fetched successfully or an error occurred
  • error: 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 object
  • maxDownloadSizeBytes: 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 occurred
  • loading: true while downloading the data of the object; false if the data was downloaded successfully or an error occurred
  • error: 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.

License

MIT