@capacitor-firebase/firestore

v8.4.0

Published

3 days ago

Capacitor plugin for Firebase Cloud Firestore on Android, iOS, and Web.

0High
0Medium
0Low

capacitor plugin native capacitor-plugin firebase firestore cloud firestore nosql database realtime data snapshot listener offline persistence

Capacitor Firebase Cloud Firestore Plugin

Unofficial Capacitor plugin for Firebase Cloud Firestore.[^1]

Use Cases

The Cloud Firestore plugin is typically used to store and sync app data in the cloud, for example:

Real-time updates: Keep your UI up to date by listening to document and collection changes with snapshot listeners.
User-generated content: Create, read, update, and delete documents for user profiles, posts, or other app data.
Complex queries: Filter and sort collections with composite filters and query constraints such as where, orderBy, and limit.
Offline support: Enable offline persistence and control network access to work with locally cached data.
Atomic writes: Perform multiple write operations as a single atomic batch with writeBatch(...).

Guides

Announcing the Capacitor Firebase Cloud Firestore Plugin

Compatibility

| Plugin Version | Capacitor Version | Status | | -------------- | ----------------- | -------------- | | 8.x.x | >=8.x.x | Active support | | 7.x.x | 7.x.x | Deprecated | | 6.x.x | 6.x.x | Deprecated |

Installation

You can use our AI-Assisted Setup to install the plugin. Add the Capawesome Skills to your AI tool using the following command:

npx skills add capawesome-team/skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-firebase/firestore` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capacitor-firebase/firestore
npx cap sync

Add Firebase to your project if you haven't already (Android / iOS / Web).

Android

Variables

If needed, you can define the following project variable in your app’s variables.gradle file to change the default version of the dependency:

$firebaseFirestoreVersion version of com.google.firebase:firebase-firestore (default: 26.0.2)

This can be useful if you encounter dependency conflicts with other plugins in your project.

iOS

Swift Package Manager

Add the following to your capacitor.config.json (or capacitor.config.ts) to avoid a SwiftPM package identity collision:

{
  "experimental": {
    "ios": {
      "spm": {
        "packageOptions": {
          "@capacitor-firebase/firestore": {
            "symlink": true
          }
        }
      }
    }
  }
}

Attention: SPM packageOptions support requires Capacitor CLI 8.4.0+.

Configuration

These configuration values are available:

| Prop | Type | Description | Since | | ---------------- | ------------------- | ------------------------------------------------------------------------------------- | ----- | | databaseId | string | The database ID of the Firestore database to use. Only available for Android and iOS. | 8.2.0 |

Examples

In capacitor.config.json:

{
  "plugins": {
    "FirebaseFirestore": {
      "databaseId": undefined
    }
  }
}

In capacitor.config.ts:

/// <reference types="@capacitor-firebase/firestore" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    FirebaseFirestore: {
      databaseId: undefined,
    },
  },
};

export default config;

Demo

A working example can be found here: robingenz/capacitor-firebase-plugin-demo

Starter templates

The following starter templates are available:

Ionstarter Angular Firebase

Usage

The following examples show how to create, read, update, and delete documents, update documents with field values, perform batched writes, query collections, control network access, use the Firebase Emulator, and listen for and remove real-time updates.

Create a document

Add a new document to a collection with an auto-generated ID, or write a document at a known reference with setDocument(...). Set merge to true to merge the data with an existing document:

import { FirebaseFirestore } from '@capacitor-firebase/firestore';

const addDocument = async () => {
  await FirebaseFirestore.addDocument({
    reference: 'users',
    data: { 
      first: 'Alan', 
      last: 'Turing', 
      born: 1912 
    },
  });
};

const setDocument = async () => {
  await FirebaseFirestore.setDocument({
    reference: 'users/Aorq09lkt1ynbR7xhTUx',
    data: { 
      first: 'Alan', 
      last: 'Turing', 
      born: 1912 
    },
    merge: true,
  });
};

Read a document

Read a single document by its reference:

import { FirebaseFirestore } from '@capacitor-firebase/firestore';

const getDocument = async () => {
  const { snapshot } = await FirebaseFirestore.getDocument({
    reference: 'users/Aorq09lkt1ynbR7xhTUx',
  });
  return snapshot;
};

Update or delete a document

Update fields of an existing document or delete it entirely:

import { FirebaseFirestore } from '@capacitor-firebase/firestore';

const updateDocument = async () => {
  await FirebaseFirestore.updateDocument({
    reference: 'users/Aorq09lkt1ynbR7xhTUx',
    data: { 
      first: 'Alan', 
      last: 'Turing', 
      born: 1912 
    },
  });
};

const deleteDocument = async () => {
  await FirebaseFirestore.deleteDocument({
    reference: 'users/Aorq09lkt1ynbR7xhTUx',
  });
};

Update a document with field values

Use FieldValue helpers to increment numbers, set server timestamps, modify arrays, or delete fields:

import { FieldValue, FirebaseFirestore } from '@capacitor-firebase/firestore';

const updateDocumentWithFieldValue = async () => {
  await FirebaseFirestore.updateDocument({
    reference: 'users/Aorq09lkt1ynbR7xhTUx',
    data: {
      born: FieldValue.increment(1),
      updatedAt: FieldValue.serverTimestamp(),
      nicknames: FieldValue.arrayUnion('Prof'),
      tags: FieldValue.arrayRemove('draft'),
      deprecatedField: FieldValue.delete(),
    },
  });
};

Perform a batched write

Execute multiple set, update, and delete operations as a single atomic batch:

import { FirebaseFirestore } from '@capacitor-firebase/firestore';

const writeBatch = async () => {
  await FirebaseFirestore.writeBatch({
    operations: [
      {
        type: 'set',
        reference: 'users/Aorq09lkt1ynbR7xhTUx',
        data: { 
          first: 'Alan', 
          last: 'Turing', 
          born: 1912 
        },
        options: { merge: true },
      },
      {
        type: 'update',
        reference: 'users/Aorq09lkt1ynbR7xhTUx',
        data: { 
          first: 'Alan', 
          last: 'Turing', 
          born: 1912 
        },
      },
      {
        type: 'delete',
        reference: 'users/Aorq09lkt1ynbR7xhTUx',
      },
    ],
  });
};

Query a collection

Read multiple documents from a collection or a collection group. You can filter the results with a composite filter and apply query constraints such as orderBy and limit:

import { FirebaseFirestore } from '@capacitor-firebase/firestore';

const getCollection = async () => {
  const { snapshots } = await FirebaseFirestore.getCollection({
    reference: 'users',
    compositeFilter: {
      type: 'and',
      queryConstraints: [
        {
          type: 'where',
          fieldPath: 'born',
          opStr: '==',
          value: 1912,
        },
      ],
    },
    queryConstraints: [
      {
        type: 'orderBy',
        fieldPath: 'born',
        directionStr: 'desc',
      },
      {
        type: 'limit',
        limit: 10,
      },
    ],
  });
  return snapshots;
};

const getCollectionGroup = async () => {
  const { snapshots } = await FirebaseFirestore.getCollectionGroup({
    reference: 'users',
    compositeFilter: {
      type: 'and',
      queryConstraints: [
        {
          type: 'where',
          fieldPath: 'born',
          opStr: '==',
          value: 1912,
        },
      ],
    },
    queryConstraints: [
      {
        type: 'orderBy',
        fieldPath: 'born',
        directionStr: 'desc',
      },
      {
        type: 'limit',
        limit: 10,
      },
    ],
  });
  return snapshots;
};

Control network access

Disable and re-enable the use of the network, for example to force the plugin to work with locally cached data:

import { FirebaseFirestore } from '@capacitor-firebase/firestore';

const enableNetwork = async () => {
  await FirebaseFirestore.enableNetwork();
};

const disableNetwork = async () => {
  await FirebaseFirestore.disableNetwork();
};

Use the Firebase Emulator

Connect the plugin to a local Firebase Emulator instance during development:

import { FirebaseFirestore } from '@capacitor-firebase/firestore';

const useEmulator = async () => {
  await FirebaseFirestore.useEmulator({
    host: '10.0.2.2',
    port: 9001,
  });
};

Listen for real-time updates

Attach snapshot listeners to a document, a collection, or a collection group to get notified whenever the data changes:

import { FirebaseFirestore } from '@capacitor-firebase/firestore';

const addDocumentSnapshotListener = async () => {
  const callbackId = await FirebaseFirestore.addDocumentSnapshotListener(
    {
      reference: 'users/Aorq09lkt1ynbR7xhTUx',
    },
    (event, error) => {
      if (error) {
        console.error(error);
      } else {
        console.log(event);
      }
    }
  );
  return callbackId;
};

const addCollectionSnapshotListener = async () => {
  const callbackId = await FirebaseFirestore.addCollectionSnapshotListener(
    {
      reference: 'users',
      compositeFilter: {
        type: 'and',
        queryConstraints: [
          {
            type: 'where',
            fieldPath: 'born',
            opStr: '==',
            value: 1912,
          },
        ],
      },
      queryConstraints: [
        {
          type: 'orderBy',
          fieldPath: 'born',
          directionStr: 'desc',
        },
        {
          type: 'limit',
          limit: 10,
        },
      ],
    },
    (event, error) => {
      if (error) {
        console.error(error);
      } else {
        console.log(event);
      }
    }
  );
  return callbackId;
};

const addCollectionGroupSnapshotListener = async () => {
  const callbackId = await FirebaseFirestore.addCollectionGroupSnapshotListener(
    {
      reference: 'users',
      compositeFilter: {
        type: 'and',
        queryConstraints: [
          {
            type: 'where',
            fieldPath: 'born',
            opStr: '==',
            value: 1912,
          },
        ],
      },
      queryConstraints: [
        {
          type: 'orderBy',
          fieldPath: 'born',
          directionStr: 'desc',
        },
        {
          type: 'limit',
          limit: 10,
        },
      ],
    },
    (event, error) => {
      if (error) {
        console.error(error);
      } else {
        console.log(event);
      }
    }
  );
  return callbackId;
};

Remove listeners

Remove a single snapshot listener by its callback ID or remove all listeners at once:

import { FirebaseFirestore } from '@capacitor-firebase/firestore';

const removeSnapshotListener = async (callbackId: string) => {
  await FirebaseFirestore.removeSnapshotListener({
    callbackId,
  });
};

const removeAllListeners = async () => {
  await FirebaseFirestore.removeAllListeners();
};

API

addDocument(...)

addDocument(options: AddDocumentOptions) => Promise<AddDocumentResult>

Adds a new document to a collection with the given data.

| Param | Type | | ------------- | ----------------------------------------------------------------- | | options | AddDocumentOptions |

Returns: Promise<AddDocumentResult>

Since: 5.2.0

addCollectionGroupSnapshotListener(...)

addCollectionGroupSnapshotListener<T extends DocumentData = DocumentData>(options: AddCollectionGroupSnapshotListenerOptions, callback: AddCollectionGroupSnapshotListenerCallback<T>) => Promise<CallbackId>

Adds a listener for collection group snapshot events.

| Param | Type | | -------------- | -------------------------------------------------------------------------------------------------------------------------- | | options | AddCollectionGroupSnapshotListenerOptions | | callback | AddCollectionGroupSnapshotListenerCallback<T> |

Returns: Promise<string>

Since: 6.1.0

addCollectionSnapshotListener(...)

addCollectionSnapshotListener<T extends DocumentData = DocumentData>(options: AddCollectionSnapshotListenerOptions, callback: AddCollectionSnapshotListenerCallback<T>) => Promise<CallbackId>

Adds a listener for collection snapshot events.

| Param | Type | | -------------- | ---------------------------------------------------------------------------------------------------------------- | | options | AddCollectionSnapshotListenerOptions | | callback | AddCollectionSnapshotListenerCallback<T> |

Returns: Promise<string>

Since: 5.2.0

addDocumentSnapshotListener(...)

addDocumentSnapshotListener<T extends DocumentData = DocumentData>(options: AddDocumentSnapshotListenerOptions, callback: AddDocumentSnapshotListenerCallback<T>) => Promise<CallbackId>

Adds a listener for document snapshot events.

| Param | Type | | -------------- | ------------------------------------------------------------------------------------------------------------ | | options | AddDocumentSnapshotListenerOptions | | callback | AddDocumentSnapshotListenerCallback<T> |

Returns: Promise<string>

Since: 5.2.0

clearPersistence()

clearPersistence() => Promise<void>

Clears the persistent storage. This includes pending writes and cached documents.

Attention: Must be called after the app is shutdown or when the app is first initialized.

Since: 5.2.0

deleteDocument(...)

deleteDocument(options: DeleteDocumentOptions) => Promise<void>

Deletes the document referred to by the specified reference.

| Param | Type | | ------------- | ----------------------------------------------------------------------- | | options | DeleteDocumentOptions |

Since: 5.2.0

disableNetwork()

disableNetwork() => Promise<void>

Disables use of the network.

Since: 5.2.0

disablePersistence()

disablePersistence() => Promise<void>

Disables offline persistence.

Attention: Must be called before any other Firestore method.

Since: 8.2.0

enablePersistence(...)

enablePersistence(options?: EnablePersistenceOptions | undefined) => Promise<void>

Enables offline persistence.

Attention: Must be called before any other Firestore method.

| Param | Type | | ------------- | ----------------------------------------------------------------------------- | | options | EnablePersistenceOptions |

Since: 8.2.0

enableNetwork()

enableNetwork() => Promise<void>

Re-enables use of the network.

Since: 5.2.0

getCollection(...)

getCollection<T extends DocumentData = DocumentData>(options: GetCollectionOptions) => Promise<GetCollectionResult<T>>

Reads the collection referenced by the specified reference.

| Param | Type | | ------------- | --------------------------------------------------------------------- | | options | GetCollectionOptions |

Returns: Promise<GetCollectionResult<T>>

Since: 5.2.0

getCollectionGroup(...)

getCollectionGroup<T extends DocumentData = DocumentData>(options: GetCollectionGroupOptions) => Promise<GetCollectionGroupResult<T>>

Reads the collection group referenced by the specified reference.

| Param | Type | | ------------- | ------------------------------------------------------------------------------- | | options | GetCollectionGroupOptions |

Returns: Promise<GetCollectionGroupResult<T>>

getCountFromServer(...)

getCountFromServer(options: GetCountFromServerOptions) => Promise<GetCountFromServerResult>

Fetches the number of documents in a collection.

| Param | Type | | ------------- | ------------------------------------------------------------------------------- | | options | GetCountFromServerOptions |

Returns: Promise<GetCountFromServerResult>

Since: 6.4.0

getDocument(...)

getDocument<T extends DocumentData = DocumentData>(options: GetDocumentOptions) => Promise<GetDocumentResult<T>>

Reads the document referred to by the specified reference.

| Param | Type | | ------------- | ----------------------------------------------------------------- | | options | GetDocumentOptions |

Returns: Promise<GetDocumentResult<T>>

Since: 5.2.0

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 5.2.0

removeSnapshotListener(...)

removeSnapshotListener(options: RemoveSnapshotListenerOptions) => Promise<void>

Remove a listener for document or collection snapshot events.

| Param | Type | | ------------- | --------------------------------------------------------------------------------------- | | options | RemoveSnapshotListenerOptions |

Since: 5.2.0

setDocument(...)

setDocument(options: SetDocumentOptions) => Promise<void>

Writes to the document referred to by the specified reference. If the document does not yet exist, it will be created.

| Param | Type | | ------------- | ----------------------------------------------------------------- | | options | SetDocumentOptions |

Since: 5.2.0

updateDocument(...)

updateDocument(options: UpdateDocumentOptions) => Promise<void>

Updates fields in the document referred to by the specified reference.

| Param | Type | | ------------- | ----------------------------------------------------------------------- | | options | UpdateDocumentOptions |

Since: 5.2.0

useEmulator(...)

useEmulator(options: UseEmulatorOptions) => Promise<void>

Instrument your app to talk to the Firestore emulator.

| Param | Type | | ------------- | ----------------------------------------------------------------- | | options | UseEmulatorOptions |

Since: 6.1.0

writeBatch(...)

writeBatch(options: WriteBatchOptions) => Promise<void>

Execute multiple write operations as a single batch.

| Param | Type | | ------------- | --------------------------------------------------------------- | | options | WriteBatchOptions |

Since: 6.1.0

Interfaces

AddDocumentResult

| Prop | Type | Description | Since | | --------------- | ------------------------------ | ------------------------------------------ | ----- | | reference | DocumentReference | The reference of the newly added document. | 5.2.0 |

AddDocumentOptions

| Prop | Type | Description | Since | | --------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------- | ----- | | reference | string | The reference as a string, with path components separated by a forward slash (/). | 5.2.0 | | data | DocumentData | An object containing the data for the new document. | 5.2.0 |

DocumentData

AddCollectionGroupSnapshotListenerOptions

| Prop | Type | Description | Since | | ---------------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ----- | | reference | string | The reference as a string, with path components separated by a forward slash (/). | 6.1.0 | | compositeFilter | QueryCompositeFilterConstraint | The filter to apply. | 6.1.0 | | queryConstraints | QueryNonFilterConstraint[] | Narrow or order the set of documents to retrieve, but do not explicitly filter for document fields. | 6.1.0 |

QueryCompositeFilterConstraint

| Prop | Type | Description | Since | | ---------------------- | ------------------------------------ | --------------------------- | ----- | | type | 'and' | 'or' | The type of the constraint. | 5.2.0 | | queryConstraints | QueryFilterConstraint[] | The filters to apply. | 5.2.0 |

QueryFieldFilterConstraint

| Prop | Type | Description | Since | | --------------- | ------------------------------------------------------- | ------------------------------ | ----- | | type | 'where' | The type of the constraint. | 5.2.0 | | fieldPath | string | The path to compare. | 5.2.0 | | opStr | QueryOperator | The operation string to apply. | 5.2.0 | | value | any | The value for comparison. | 5.2.0 |

QueryOrderByConstraint

| Prop | Type | Description | Since | | ------------------ | ------------------------------------------------------------- | --------------------------- | ----- | | type | 'orderBy' | The type of the constraint. | 5.2.0 | | fieldPath | string | The path to compare. | 5.2.0 | | directionStr | OrderByDirection | The direction to sort by. | 5.2.0 |

QueryLimitConstraint

| Prop | Type | Description | Since | | ----------- | ------------------------------------- | -------------------------------------- | ----- | | type | 'limit' | 'limitToLast' | The type of the constraint. | 5.2.0 | | limit | number | The maximum number of items to return. | 5.2.0 |

QueryStartAtConstraint

| Prop | Type | Description | Since | | --------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | | type | 'startAt' | 'startAfter' | The type of the constraint. | 5.2.0 | | reference | string | The reference to start at or after as a string, with path components separated by a forward slash (/). Attention: This requires an additional document read. | 5.2.0 |

QueryEndAtConstraint

| Prop | Type | Description | Since | | --------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | type | 'endAt' | 'endBefore' | The type of the constraint. | 5.2.0 | | reference | string | The reference as to end at or before as a string, with path components separated by a forward slash (/). Attention: This requires an additional document read. | 5.2.0 |

GetCollectionGroupResult

| Prop | Type | Description | Since | | --------------- | ------------------------------------------------------------------------ | -------------------------------- | ----- | | snapshots | DocumentSnapshot<T>[] | The documents in the collection. | 5.2.0 |

DocumentSnapshot

| Prop | Type | Description | Since | | -------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ----- | | id | string | The document's identifier within its collection. | 5.2.0 | | path | string | The path of the document. | 5.2.0 | | data | T | null | An object containing the data for the document. Returns null if the document doesn't exist. | 5.2.0 | | metadata | SnapshotMetadata | Metadata about the snapshot, concerning its source and if it has local modifications. | 6.2.0 |

SnapshotMetadata

| Prop | Type | Description | Since | | ---------------------- | -------------------- | --------------------------------------------------------- | ----- | | fromCache | boolean | True if the snapshot was created from cached data. | 6.2.0 | | hasPendingWrites | boolean | True if the snapshot was created from pending write data. | 6.2.0 |

AddCollectionSnapshotListenerOptions

| Prop | Type | Description | Since | | ---------------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ----- | | reference | string | The reference as a string, with path components separated by a forward slash (/). | 5.2.0 | | compositeFilter | QueryCompositeFilterConstraint | The filter to apply. | 5.2.0 | | queryConstraints | QueryNonFilterConstraint[] | Narrow or order the set of documents to retrieve, but do not explicitly filter for document fields. | 5.2.0 |

GetCollectionResult

AddDocumentSnapshotListenerOptions

| Prop | Type | Description | Since | | --------------- | ------------------- | ----------------------------------------------------------------------------------- | ----- | | reference | string | The reference as a string, with path components separated by a forward slash (/). | 5.2.0 |

GetDocumentResult

| Prop | Type | Description | Since | | -------------- | ---------------------------------------------------------------------- | ------------------------------ | ----- | | snapshot | DocumentSnapshot<T> | The current document contents. | 5.2.0 |

DeleteDocumentOptions

EnablePersistenceOptions

| Prop | Type | Description | Default | Since | | --------------------- | -------------------- | -------------------------------------------------------------------------------- | ------------------------------- | ----- | | cacheSizeBytes | number | The cache size in bytes. | 104857600 (100 MB) | 8.2.0 | | synchronizeTabs | boolean | Whether to synchronize persistence across multiple tabs. Only available for Web. | false | 8.2.0 |

GetCollectionOptions

| Prop | Type | Description | Since | | ---------------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ----- | | reference | string | The reference as a string, with path components separated by a forward slash (/). | 5.2.0 | | compositeFilter | QueryCompositeFilterConstraint | The filter to apply. | 5.2.0 | | queryConstraints | QueryNonFilterConstraint[] | Narrow or order the set of documents to retrieve, but do not explicitly filter for document fields. | 5.2.0 |

GetCollectionGroupOptions

| Prop | Type | Description | Since | | ---------------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ----- | | reference | string | The reference as a string, with path components separated by a forward slash (/). | 5.2.0 | | compositeFilter | QueryCompositeFilterConstraint | The filter to apply. | 5.2.0 | | queryConstraints | QueryNonFilterConstraint[] | Narrow or order the set of documents to retrieve, but do not explicitly filter for document fields. | 5.2.0 |

GetCountFromServerResult

| Prop | Type | Description | Since | | ----------- | ------------------- | ------------------------------------------ | ----- | | count | number | The number of documents in the collection. | 6.4.0 |

GetCountFromServerOptions

| Prop | Type | Description | Since | | ---------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ----- | | reference | string | The reference as a string, with path components separated by a forward slash (/). | 6.4.0 | | compositeFilter | QueryCompositeFilterConstraint | The filter to apply. | 8.3.0 | | queryConstraints | QueryNonFilterConstraint[] | Narrow or order the set of documents to count, but do not explicitly filter for document fields. | 8.3.0 |

GetDocumentOptions

RemoveSnapshotListenerOptions

| Prop | Type | Since | | ---------------- | ------------------------------------------------- | ----- | | callbackId | CallbackId | 5.2.0 |

SetDocumentOptions

| Prop | Type | Description | Default | Since | | --------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------ | ----- | | reference | string | The reference as a string, with path components separated by a forward slash (/). | | 5.2.0 | | data | DocumentData | An object containing the data for the new document. | | 5.2.0 | | merge | boolean | Whether to merge the provided data with an existing document. | false | 5.2.0 |

UpdateDocumentOptions

UseEmulatorOptions

| Prop | Type | Description | Default | Since | | ---------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ----- | | host | string | The emulator host without any port or scheme. Note when using a Android Emulator device: 10.0.2.2 is the special IP address to connect to the 'localhost' of the host computer. | | 6.1.0 | | port | number | The emulator port. | 8080 | 6.1.0 |

WriteBatchOptions

| Prop | Type | Description | Since | | ---------------- | ---------------------------------- | --------------------------------------- | ----- | | operations | WriteBatchOperation[] | The operations to execute in the batch. | 6.1.0 |

WriteBatchOperation

| Prop | Type | Description | Since | | --------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------- | ----- | | type | 'set' | 'update' | 'delete' | The type of operation. | 6.1.0 | | reference | string | The reference as a string, with path components separated by a forward slash (/). | 6.1.0 | | data | DocumentData | An object containing the data for the new document. | 6.1.0 | | options | SetOptions | An object to configure the set behavior. | 7.3.0 |

SetOptions

| Prop | Type | Description | Default | Since | | ----------- | -------------------- | -------------------------------------------------------------------------- | ------------------ | ----- | | merge | boolean | Whether a merge should be performed or the document should be overwritten. | false | 7.3.0 |

Type Aliases

QueryFilterConstraint

QueryFieldFilterConstraint | QueryCompositeFilterConstraint

QueryOperator

'<' | '<=' | '==' | '>=' | '>' | '!=' | 'array-contains' | 'array-contains-any' | 'in' | 'not-in'

QueryNonFilterConstraint

QueryOrderByConstraint | QueryLimitConstraint | QueryStartAtConstraint | QueryEndAtConstraint

OrderByDirection

'desc' | 'asc'

AddCollectionGroupSnapshotListenerCallback

(event: AddCollectionGroupSnapshotListenerCallbackEvent<T> | null, error: any): void

AddCollectionGroupSnapshotListenerCallbackEvent

GetCollectionGroupResult<T>

CallbackId

string

AddCollectionSnapshotListenerCallback

(event: AddCollectionSnapshotListenerCallbackEvent<T> | null, error: any): void

AddCollectionSnapshotListenerCallbackEvent

GetCollectionResult<T>

AddDocumentSnapshotListenerCallback

(event: AddDocumentSnapshotListenerCallbackEvent<T> | null, error: any): void

AddDocumentSnapshotListenerCallbackEvent

GetDocumentResult<T>

FAQ

How do I get notified about data changes in real time?

Attach a snapshot listener with addDocumentSnapshotListener(...), addCollectionSnapshotListener(...), or addCollectionGroupSnapshotListener(...). The callback is invoked whenever the observed data changes. Each listener returns a callback ID that you can later pass to removeSnapshotListener(...), or you can remove all listeners at once with removeAllListeners(). See Listen for real-time updates for an example.

What is the difference between `getCollection` and `getCollectionGroup`?

The getCollection(...) method reads the documents of a single collection at the given reference. The getCollectionGroup(...) method reads the documents of a collection group, which consists of all collections with the same ID. Both methods support composite filters and query constraints.

Does the plugin work offline?

Yes, you can enable offline persistence with the enablePersistence(...) method, which must be called before any other Firestore method. You can also disable and re-enable the use of the network with disableNetwork() and enableNetwork(). The persistent storage, including pending writes and cached documents, can be cleared with clearPersistence(), which must be called after the app is shut down or when it is first initialized.

Can I use a Firestore database other than the default one?

Yes, you can set the databaseId configuration option in your Capacitor configuration to select the Firestore database to use (see Configuration). This option is only available on Android and iOS.

How do I test my app against a local Firestore instance?

Use the useEmulator(...) method to connect the plugin to a local Firebase Emulator instance by providing its host and port. This allows you to develop and test without touching your production data.

Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

Related Plugins

Firebase Authentication: Unofficial Capacitor plugin for Firebase Authentication.
Firebase Cloud Functions: Unofficial Capacitor plugin for Firebase Cloud Functions.
Firebase Cloud Storage: Unofficial Capacitor plugin for Firebase Cloud Storage.

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our Capawesome Newsletter.

Changelog

See CHANGELOG.md.

License

See LICENSE.

[^1]: This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Capacitor Firebase Cloud Firestore Plugin

Use Cases

Guides

Compatibility

Installation

Android

Variables

iOS

Swift Package Manager

Configuration

Examples

Demo

Starter templates

Usage

Create a document

Read a document

Update or delete a document

Update a document with field values

Perform a batched write

Query a collection

Control network access

Use the Firebase Emulator

Listen for real-time updates

Remove listeners

API

addDocument(...)

addCollectionGroupSnapshotListener(...)

addCollectionSnapshotListener(...)

addDocumentSnapshotListener(...)

clearPersistence()

deleteDocument(...)

disableNetwork()

disablePersistence()

enablePersistence(...)

enableNetwork()

getCollection(...)

getCollectionGroup(...)

getCountFromServer(...)

getDocument(...)

removeAllListeners()

removeSnapshotListener(...)

setDocument(...)

updateDocument(...)

useEmulator(...)

writeBatch(...)

Interfaces

AddDocumentResult

AddDocumentOptions

DocumentData

AddCollectionGroupSnapshotListenerOptions

QueryCompositeFilterConstraint

QueryFieldFilterConstraint

QueryOrderByConstraint

QueryLimitConstraint

QueryStartAtConstraint

QueryEndAtConstraint

GetCollectionGroupResult

DocumentSnapshot

SnapshotMetadata

AddCollectionSnapshotListenerOptions

GetCollectionResult

AddDocumentSnapshotListenerOptions

GetDocumentResult

DeleteDocumentOptions

EnablePersistenceOptions

GetCollectionOptions

GetCollectionGroupOptions

GetCountFromServerResult

GetCountFromServerOptions

GetDocumentOptions

RemoveSnapshotListenerOptions

SetDocumentOptions

UpdateDocumentOptions

UseEmulatorOptions

What is the difference between `getCollection` and `getCollectionGroup`?