{"id":13481387,"url":"https://github.com/green-arrow/react-firestore","last_synced_at":"2025-04-05T09:06:25.217Z","repository":{"id":28262790,"uuid":"117615369","full_name":"green-arrow/react-firestore","owner":"green-arrow","description":"React components to fetch data from firestore using render props","archived":false,"fork":false,"pushed_at":"2022-12-07T09:03:44.000Z","size":1973,"stargazers_count":229,"open_issues_count":41,"forks_count":23,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-03-29T08:08:03.645Z","etag":null,"topics":["firebase","firestore","firestore-database","react","render-props"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/green-arrow.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-01-16T01:35:49.000Z","updated_at":"2023-11-20T16:00:11.000Z","dependencies_parsed_at":"2022-08-07T13:15:37.454Z","dependency_job_id":null,"html_url":"https://github.com/green-arrow/react-firestore","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/green-arrow%2Freact-firestore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/green-arrow%2Freact-firestore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/green-arrow%2Freact-firestore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/green-arrow%2Freact-firestore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/green-arrow","download_url":"https://codeload.github.com/green-arrow/react-firestore/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247312077,"owners_count":20918344,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["firebase","firestore","firestore-database","react","render-props"],"created_at":"2024-07-31T17:00:51.404Z","updated_at":"2025-04-05T09:06:25.164Z","avatar_url":"https://github.com/green-arrow.png","language":"JavaScript","funding_links":[],"categories":["Components","JavaScript"],"sub_categories":["Data"],"readme":"[![Build Status][build-badge]][build]\n[![codecov][coverage-badge]][coverage]\n[![MIT License][license-badge]][license]\n[![version][version-badge]][package]\n\n[![size][size-badge]][unpkg-dist]\n[![gzip size][gzip-badge]][unpkg-dist]\n[![module formats: umd, cjs, and es][module-formats-badge]][unpkg-dist]\n\n# react-firestore 🔥🏪\n\nReact components to fetch collections and documents from Firestore\n\n## The problem\n\nYou want to use the new Firestore database from Google, but don't want to\nhave to use redux or any other state management tool. You would like to not have\nto worry too much about the exact API for firestore (snapshots, references, etc),\nand just be able to retrieve collections and documents and read their data.\n\nYou also want to do all this using [render props, because they're awesome](https://www.youtube.com/watch?v=BcVAq3YFiuc).\n\n## The solution\n\nThis is a set of components that allows you to interact with Firestore collections\nand documents, without needing to constantly call additional methods (like `.data()`)\nto display your data.\n\nThere is still an escape hatch where the snapshot from Firestore is provided to\nyour render function, in the event that you need more control over your interactions\nwith Firestore.\n\n## Disclaimer\n\nThis project is still a work in progress and in an alpha state.\nThe API may update frequently.\n\n## Table of Contents\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n* [Installation](#installation)\n* [Usage](#usage)\n  * [`FirestoreProvider`](#firestoreprovider)\n  * [`FirestoreCollection`](#firestorecollection)\n  * [`FirestoreDocument`](#firestoredocument)\n  * [`Firestore`](#firestore)\n  * [`withFirestore`](#withfirestore)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## Installation\n\nThis package is available on [npm][npm].\n\n```\nnpm install --save react-firestore\n```\n\nOr, if you're using [yarn][yarn]:\n\n```\nyarn add react-firestore\n```\n\n## Usage\n\nThere are 3 components provided with this package:\n\n* [FirestoreProvider](#firestoreprovider)\n* [FirestoreCollection](#firestorecollection)\n* [FirestoreDocument](#firestoredocument)\n\n### `FirestoreProvider`\n\nThis component allows the `FirestoreCollection` and `FirestoreDocument`\ncomponents to communicate with Firestore.\n\nAt the top level of your app, configure `firebase` and render the\n`FirestoreProvider` component.\n\nIf you're using [create-react-app][create-react-app], your `index.js`\nfile would look something like this:\n\n\n```jsx\nimport React from 'react';\nimport ReactDOM from 'react-dom';\nimport firebase from '@firebase/app';\nimport '@firebase/firestore';\nimport { FirestoreProvider } from 'react-firestore';\n\nimport App from './App';\n\nconst config = {\n  apiKey: '\u003cyour_api_key\u003e',\n  projectId: '\u003cyour_firebase_project_id\u003e',\n};\n\nfirebase.initializeApp(config);\n\nReactDOM.render(\n  \u003cFirestoreProvider firebase={firebase}\u003e\n    \u003cApp /\u003e\n  \u003c/FirestoreProvider\u003e,\n  document.getElementById('root'),\n);\n```\n\n_Important: Starting with Firebase v5.5.0 timestamp objects stored in Firestore get returned as Firebase\nTimestamp objects instead of regular Date() objects. To make your app compatible with this\nchange, add the `useTimestampsInSnapshots` to the FirestoreProvider element. If you dont do this\nyour app might break. For more information visit [the Firebase refrence documentation][https://firebase.google.com/docs/reference/js/firebase.firestore.Timestamp]._\n\n_Note: The reason for the separate imports for `@firebase/app` and `@firebase/firestore`\nis because `firestore` is not included in the default `firebase` wrapper package. See\nthe [firestore package](https://www.npmjs.com/package/@firebase/firestore) for more details._\n\n#### `FirestoreProvider` props\n\n##### firebase\n\n\u003e `firebase` | _required_\n\nAn already initialized `firebase` object from the [@firebase/app package](https://www.npmjs.com/package/@firebase/app).\n\n### `FirestoreCollection`\n\nThis component allows you to interact with a Firestore collection.\nUsing this component, you can access the collection at a given `path`\nand provide sort options, perform queries, and paginate data.\n\nThis component will setup a listener and update\nwhenever the given collection is updated in Firestore.\n\nExample usage to get a collection and sort by some fields:\n\n```jsx\n\u003cFirestoreCollection\n  path=\"stories\"\n  sort=\"publishedDate:desc,authorName\"\n  render={({ isLoading, data }) =\u003e {\n    return isLoading ? (\n      \u003cLoading /\u003e\n    ) : (\n      \u003cdiv\u003e\n        \u003ch1\u003eStories\u003c/h1\u003e\n        \u003cul\u003e\n          {data.map(story =\u003e (\n            \u003cli key={story.id}\u003e\n              {story.title} - {story.authorName}\n            \u003c/li\u003e\n          ))}\n        \u003c/ul\u003e\n      \u003c/div\u003e\n    );\n  }}\n/\u003e\n```\n\n#### `FirestoreCollection` props\n\n##### path\n\n\u003e `string` | _required_\n\nThe `/` separated path to the Firestore collection. Collections must\ncontain an odd number of path segments.\n\n##### sort\n\n\u003e `string` | defaults to `null`\n\nA comma-delimited list of fields by which the query should be ordered.\nEach item in the list can be of the format `fieldName` or `fieldName:sortOrder`.\nThe `sortOrder` piece can be either `asc` or `desc`. If just a field name is given,\n`sortOrder` defaults to `asc`.\n\n##### limit\n\n\u003e `number` | defaults to `null`\n\nThe maximum number of documents to retrieve from the collection.\n\n##### filter\n\n\u003e `array` or `array of array` | defaults to `null`\n\nPassing in an array of strings creates a simple query to filter the collection by\n\n```jsx\n\u003cFirestoreCollection\n  path={'users'}\n  filter={['firstName', '==', 'Mike']}\n  render={() =\u003e {\n    /* render stuff*/\n  }}\n/\u003e\n```\n\nPassing in an array of arrays creates a compound query to filter the collection by\n\n```jsx\n\u003cFirestoreCollection\n  path={'users'}\n  filter={[['firstName', '==', 'Mike'], ['lastName', '==', 'Smith']]}\n  render={() =\u003e {\n    /* render stuff*/\n  }}\n/\u003e\n```\n\nPassing in document references allows you to filter by reference fields:\n\n```jsx\n\u003cFirestoreCollection\n  path={'users'}\n  filter={[\n    'organization',\n    '==',\n    firestore.collection('organizations').doc('foocorp'),\n  ]}\n  render={() =\u003e {\n    /* render stuff*/\n  }}\n/\u003e\n```\n\n##### render\n\n\u003e function({}) | _required_\n\nThis is the function where you render whatever you want based on the state of\nthe `FirebaseCollection` component. The object provided to the `render` function\ncontains the following fields:\n\n| property  | type                     | description                                                                                                                                                                                         |\n| --------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| isLoading | `boolean`                | Loading status for the firebase query. `true` until an initial payload from Firestore is received.                                                                                                  |\n| error     | `Error`                  | Error received from firebase when the listen fails or is cancelled.                                                                                                                                 |\n| data      | `Array\u003cany\u003e`             | An array containing all of the documents in the collection. Each item will contain an `id` along with the other data contained in the document.                                                     |\n| snapshot  | `QuerySnapshot` / `null` | The firestore `QuerySnapshot` created to get data for the collection. See [QuerySnapshot docs](https://cloud.google.com/nodejs/docs/reference/firestore/latest/QuerySnapshot) for more information. |\n\n### `FirestoreDocument`\n\nThis component allows you to retrieve a Firestore document from the given `path`.\n\nThis component will setup a listener and update\nwhenever the given document is updated in Firestore.\n\n```jsx\n\u003cFirestoreDocument\n  path=\"stories/1\"\n  render={({ isLoading, data }) =\u003e {\n    return isLoading ? (\n      \u003cLoading /\u003e\n    ) : (\n      \u003cdiv\u003e\n        \u003ch1\u003e{data.title}\u003c/h1\u003e\n        \u003ch2\u003e\n          {data.authorName} - {data.publishedDate}\n        \u003c/h2\u003e\n        \u003cp\u003e{data.description}\u003c/p\u003e\n      \u003c/div\u003e\n    );\n  }}\n/\u003e\n```\n\n#### `FirestoreDocument` props\n\n##### path\n\n\u003e `string` | _required_\n\nThe `/` separated path to the Firestore document.\n\n##### render\n\n\u003e function({}) | _required_\n\nThis is the function where you render whatever you want based on the state of\nthe `FirebaseDocument` component. The object provided to the `render` function\ncontains the following fields:\n\n| property  | type                        | description                                                                                                                                                                                                |\n| --------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| isLoading | `boolean`                   | Loading status for the firebase query. `true` until an initial payload from Firestore is received.                                                                                                         |\n| error     | `Error`                     | Error received from firebase when parsing the document data.                                                                                                                                               |\n| data      | `Object` / `null`           | The document that resides at the given `path`. Will be `null` until an initial payload is received. The document will contain an `id` along with the other data contained in the document.                 |\n| snapshot  | `DocumentSnapshot` / `null` | The firestore `DocumentSnapshot` created to get data for the document. See [DocumentSnapshot docs](https://cloud.google.com/nodejs/docs/reference/firestore/latest/DocumentSnapshot) for more information. |\n\n### `Firestore`\n\nThis component supplies the firestore database to the function specified\nby the `render` prop. This component can be used if you need more flexibility\nthan the `FirestoreCollection` and `FirestoreDocument` components provide,\nor if you would just rather interact directly with the `firestore` object.\n\n```jsx\n\u003cFirestore\n  render={({ firestore }) =\u003e {\n    // Do stuff with `firestore`\n    return \u003cdiv\u003e /* Component markup */ \u003c/div\u003e;\n  }}\n/\u003e\n```\n\n#### `Firestore` props\n\n##### render\n\n\u003e function({}) | _required_\n\nThis is the function where you render whatever you want using the firestore\nobject passed in.\n\n| property  | type     | description                                                                                                                                   |\n| --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |\n| firestore | `Object` | The `Firestore` class from [firestore][firestore-package]. See the docs for the [Firestore class][firestore-class-docs] for more information. |\n\n### `withFirestore`\n\nThis higher-order component can be used to provide the firestore database\ndirectly to the wrapped component via the `firestore` prop.\n\n```jsx\nclass MyComponent extends Component {\n  state = {\n    story: null,\n  };\n\n  componentDidMount() {\n    const { firestore } = this.props;\n\n    firestore.doc('stories/1').onSnapshot(snapshot =\u003e {\n      this.setState({ story: snapshot });\n    });\n  }\n\n  render() {\n    const { story } = this.state;\n    const storyData = story ? story.data() : null;\n\n    return storyData ? (\n      \u003cdiv\u003e\n        \u003ch1\u003e{storyData.title}\u003c/h1\u003e\n        \u003ch2\u003e\n          {storyData.authorName} - {storyData.publishedDate}\n        \u003c/h2\u003e\n        \u003cp\u003e{storyData.description}\u003c/p\u003e\n      \u003c/div\u003e\n    ) : (\n      \u003cLoading /\u003e\n    );\n  }\n}\n\nexport default withFirestore(MyComponent);\n```\n\n#### `Component.WrappedComponent`\n\nThe wrapped component is available as a static property called\n`WrappedComponent` on the returned component. This can be used\nfor testing the component in isolation, without needing to provide\ncontext in your tests.\n\n#### Props for returned component\n\n##### wrappedComponentRef\n\n\u003e function | _optional_\n\nA function that will be passed as the `ref` prop to the wrapped component.\n\n[npm]: https://www.npmjs.com/\n[yarn]: https://yarnpkg.com/\n[firestore-package]: https://www.npmjs.com/package/@firebase/firestore\n[firestore-class-docs]: https://cloud.google.com/nodejs/docs/reference/firestore/0.11.x/Firestore\n[create-react-app]: https://github.com/facebookincubator/create-react-app\n[build-badge]: https://img.shields.io/travis/green-arrow/react-firestore.svg?style=flat-square\n[build]: https://travis-ci.org/green-arrow/react-firestore\n[coverage-badge]: https://img.shields.io/codecov/c/github/green-arrow/react-firestore.svg?style=flat-square\n[coverage]: https://codecov.io/github/green-arrow/react-firestore\n[license-badge]: https://img.shields.io/npm/l/react-firestore.svg?style=flat-square\n[license]: https://github.com/green-arrow/react-firestore/blob/master/LICENSE\n[version-badge]: https://img.shields.io/npm/v/react-firestore.svg?style=flat-square\n[package]: https://www.npmjs.com/package/react-firestore\n[gzip-badge]: http://img.badgesize.io/https://unpkg.com/react-firestore/dist/react-firestore.umd.min.js?compression=gzip\u0026label=gzip%20size\u0026style=flat-square\n[size-badge]: http://img.badgesize.io/https://unpkg.com/react-firestore/dist/react-firestore.umd.min.js?label=size\u0026style=flat-square\n[unpkg-dist]: https://unpkg.com/react-firestore/dist/\n[module-formats-badge]: https://img.shields.io/badge/module%20formats-umd%2C%20cjs%2C%20es-green.svg?style=flat-square\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgreen-arrow%2Freact-firestore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgreen-arrow%2Freact-firestore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgreen-arrow%2Freact-firestore/lists"}