--- title: Capacitor Firestore Plugin for Android, iOS & Web description: Unofficial Capacitor plugin for Firebase Cloud Firestore SDK to store and sync data in real-time with support for Android, iOS, and Web. tags: - Android - iOS - Web search: boost: 2 faq: true github_repo: capawesome-team/capacitor-firebase npm_package: "@capacitor-firebase/firestore" sponsor: name: AppScreens image: /docs/assets/images/sponsors/appscreens-logo.png url: https://appscreens.com/?_locale=en&utm_source=capawesome&utm_medium=referral&utm_campaign=capawesome&gclid=capawesome --- # Capacitor Firebase Cloud Firestore Plugin Unofficial Capacitor plugin for [Firebase Cloud Firestore](https://firebase.google.com/docs/firestore/).[^1]
Deliver Live Updates to your Capacitor app with Capawesome Cloud
## 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(...)`. ## 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 | ## Guides - [Announcing the Capacitor Firebase Cloud Firestore Plugin](https://capawesome.io/blog/announcing-the-capacitor-firebase-cloud-firestore-plugin/) - [Capacitor Firestore: Real-Time Data & Offline Sync](https://capawesome.io/blog/capacitor-firebase-cloud-firestore-guide/): Real-time listeners, offline persistence, and atomic writes with this plugin. - [How to Wrap an Angular App with Capacitor and Firebase](https://capawesome.io/blog/how-to-wrap-an-angular-app-with-capacitor-and-firebase/): Uses this plugin alongside Cloud Storage to store and sync user data. ## Installation You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command: ```bash 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: ```bash npm install @capacitor-firebase/firestore npx cap sync ``` Add Firebase to your project if you haven't already ([Android](https://github.com/capawesome-team/capacitor-firebase/blob/main/docs/firebase-setup.md#android) / [iOS](https://github.com/capawesome-team/capacitor-firebase/blob/main/docs/firebase-setup.md#ios) / [Web](https://github.com/capawesome-team/capacitor-firebase/blob/main/docs/firebase-setup.md#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](https://github.com/capawesome-team/capacitor-firebase/issues/959): ```json { "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`: ```json { "plugins": { "FirebaseFirestore": { "databaseId": undefined } } } ``` In `capacitor.config.ts`: ```ts /// 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](https://github.com/robingenz/capacitor-firebase-plugin-demo) ## Starter templates The following starter templates are available: - [Ionstarter Angular Firebase](https://ionstarter.dev/) ## 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: ```typescript 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: ```typescript 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: ```typescript 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: ```typescript 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: ```typescript 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`: ```typescript 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: ```typescript 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](https://firebase.google.com/docs/emulator-suite) instance during development: ```typescript 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: ```typescript 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: ```typescript import { FirebaseFirestore } from '@capacitor-firebase/firestore'; const removeSnapshotListener = async (callbackId: string) => { await FirebaseFirestore.removeSnapshotListener({ callbackId, }); }; const removeAllListeners = async () => { await FirebaseFirestore.removeAllListeners(); }; ``` ## API * [`addDocument(...)`](#adddocument) * [`addCollectionGroupSnapshotListener(...)`](#addcollectiongroupsnapshotlistener) * [`addCollectionSnapshotListener(...)`](#addcollectionsnapshotlistener) * [`addDocumentSnapshotListener(...)`](#adddocumentsnapshotlistener) * [`clearPersistence()`](#clearpersistence) * [`deleteDocument(...)`](#deletedocument) * [`disableNetwork()`](#disablenetwork) * [`disablePersistence()`](#disablepersistence) * [`enablePersistence(...)`](#enablepersistence) * [`enableNetwork()`](#enablenetwork) * [`getCollection(...)`](#getcollection) * [`getCollectionGroup(...)`](#getcollectiongroup) * [`getCountFromServer(...)`](#getcountfromserver) * [`getDocument(...)`](#getdocument) * [`removeAllListeners()`](#removealllisteners) * [`removeSnapshotListener(...)`](#removesnapshotlistener) * [`setDocument(...)`](#setdocument) * [`updateDocument(...)`](#updatedocument) * [`useEmulator(...)`](#useemulator) * [`writeBatch(...)`](#writebatch) * [Interfaces](#interfaces) * [Type Aliases](#type-aliases) ### addDocument(...) ```typescript addDocument(options: AddDocumentOptions) => Promise ``` Adds a new document to a collection with the given data. | Param | Type | | ------------- | ----------------------------------------------------------------- | | **`options`** | AddDocumentOptions | **Returns:** Promise<AddDocumentResult> **Since:** 5.2.0 -------------------- ### addCollectionGroupSnapshotListener(...) ```typescript addCollectionGroupSnapshotListener(options: AddCollectionGroupSnapshotListenerOptions, callback: AddCollectionGroupSnapshotListenerCallback) => Promise ``` Adds a listener for collection group snapshot events. | Param | Type | | -------------- | -------------------------------------------------------------------------------------------------------------------------- | | **`options`** | AddCollectionGroupSnapshotListenerOptions | | **`callback`** | AddCollectionGroupSnapshotListenerCallback<T> | **Returns:** Promise<string> **Since:** 6.1.0 -------------------- ### addCollectionSnapshotListener(...) ```typescript addCollectionSnapshotListener(options: AddCollectionSnapshotListenerOptions, callback: AddCollectionSnapshotListenerCallback) => Promise ``` Adds a listener for collection snapshot events. | Param | Type | | -------------- | ---------------------------------------------------------------------------------------------------------------- | | **`options`** | AddCollectionSnapshotListenerOptions | | **`callback`** | AddCollectionSnapshotListenerCallback<T> | **Returns:** Promise<string> **Since:** 5.2.0 -------------------- ### addDocumentSnapshotListener(...) ```typescript addDocumentSnapshotListener(options: AddDocumentSnapshotListenerOptions, callback: AddDocumentSnapshotListenerCallback) => Promise ``` Adds a listener for document snapshot events. | Param | Type | | -------------- | ------------------------------------------------------------------------------------------------------------ | | **`options`** | AddDocumentSnapshotListenerOptions | | **`callback`** | AddDocumentSnapshotListenerCallback<T> | **Returns:** Promise<string> **Since:** 5.2.0 -------------------- ### clearPersistence() ```typescript clearPersistence() => Promise ``` 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(...) ```typescript deleteDocument(options: DeleteDocumentOptions) => Promise ``` Deletes the document referred to by the specified reference. | Param | Type | | ------------- | ----------------------------------------------------------------------- | | **`options`** | DeleteDocumentOptions | **Since:** 5.2.0 -------------------- ### disableNetwork() ```typescript disableNetwork() => Promise ``` Disables use of the network. **Since:** 5.2.0 -------------------- ### disablePersistence() ```typescript disablePersistence() => Promise ``` Disables offline persistence. **Attention**: Must be called before any other Firestore method. **Since:** 8.2.0 -------------------- ### enablePersistence(...) ```typescript enablePersistence(options?: EnablePersistenceOptions | undefined) => Promise ``` Enables offline persistence. **Attention**: Must be called before any other Firestore method. | Param | Type | | ------------- | ----------------------------------------------------------------------------- | | **`options`** | EnablePersistenceOptions | **Since:** 8.2.0 -------------------- ### enableNetwork() ```typescript enableNetwork() => Promise ``` Re-enables use of the network. **Since:** 5.2.0 -------------------- ### getCollection(...) ```typescript getCollection(options: GetCollectionOptions) => Promise> ``` Reads the collection referenced by the specified reference. | Param | Type | | ------------- | --------------------------------------------------------------------- | | **`options`** | GetCollectionOptions | **Returns:** Promise<GetCollectionResult<T>> **Since:** 5.2.0 -------------------- ### getCollectionGroup(...) ```typescript getCollectionGroup(options: GetCollectionGroupOptions) => Promise> ``` Reads the collection group referenced by the specified reference. | Param | Type | | ------------- | ------------------------------------------------------------------------------- | | **`options`** | GetCollectionGroupOptions | **Returns:** Promise<GetCollectionGroupResult<T>> -------------------- ### getCountFromServer(...) ```typescript getCountFromServer(options: GetCountFromServerOptions) => Promise ``` Fetches the number of documents in a collection. | Param | Type | | ------------- | ------------------------------------------------------------------------------- | | **`options`** | GetCountFromServerOptions | **Returns:** Promise<GetCountFromServerResult> **Since:** 6.4.0 -------------------- ### getDocument(...) ```typescript getDocument(options: GetDocumentOptions) => Promise> ``` Reads the document referred to by the specified reference. | Param | Type | | ------------- | ----------------------------------------------------------------- | | **`options`** | GetDocumentOptions | **Returns:** Promise<GetDocumentResult<T>> **Since:** 5.2.0 -------------------- ### removeAllListeners() ```typescript removeAllListeners() => Promise ``` Remove all listeners for this plugin. **Since:** 5.2.0 -------------------- ### removeSnapshotListener(...) ```typescript removeSnapshotListener(options: RemoveSnapshotListenerOptions) => Promise ``` Remove a listener for document or collection snapshot events. | Param | Type | | ------------- | --------------------------------------------------------------------------------------- | | **`options`** | RemoveSnapshotListenerOptions | **Since:** 5.2.0 -------------------- ### setDocument(...) ```typescript setDocument(options: SetDocumentOptions) => Promise ``` 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(...) ```typescript updateDocument(options: UpdateDocumentOptions) => Promise ``` Updates fields in the document referred to by the specified reference. | Param | Type | | ------------- | ----------------------------------------------------------------------- | | **`options`** | UpdateDocumentOptions | **Since:** 5.2.0 -------------------- ### useEmulator(...) ```typescript useEmulator(options: UseEmulatorOptions) => Promise ``` Instrument your app to talk to the Firestore emulator. | Param | Type | | ------------- | ----------------------------------------------------------------- | | **`options`** | UseEmulatorOptions | **Since:** 6.1.0 -------------------- ### writeBatch(...) ```typescript writeBatch(options: WriteBatchOptions) => Promise ``` 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 | Prop | Type | Description | Since | | --------------- | ------------------------------------------------------------------------ | -------------------------------- | ----- | | **`snapshots`** | DocumentSnapshot<T>[] | The documents in the collection. | 5.2.0 | #### 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 | Prop | Type | Description | Since | | --------------- | ------------------- | ----------------------------------------------------------------------------------- | ----- | | **`reference`** | string | The reference as a string, with path components separated by a forward slash (`/`). | 5.2.0 | #### 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 | Prop | Type | Description | Since | | --------------- | ------------------- | ----------------------------------------------------------------------------------- | ----- | | **`reference`** | string | The reference as a string, with path components separated by a forward slash (`/`). | 5.2.0 | #### 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 | 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 | #### 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](#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](#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](https://capawesome.io/docs/sdks/capacitor/firebase/authentication/): Unofficial Capacitor plugin for Firebase Authentication. - [Firebase Cloud Functions](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-functions/): Unofficial Capacitor plugin for Firebase Cloud Functions. - [Firebase Cloud Storage](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-storage/): Unofficial Capacitor plugin for Firebase Cloud Storage. ## Newsletter Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/). ## Changelog See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/firestore/CHANGELOG.md). ## License See [LICENSE](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/firestore/LICENSE). [^1]: This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries.