1---
2category: '@Firebase'
3---
4 
5# useFirestore
6 
7Reactive [Firestore](https://firebase.google.com/docs/firestore) binding. Making it straightforward to **always keep your local data in sync** with remotes databases.
8 
9## Usage
10 
11```ts {9,12,17,22}
12import { useFirestore } from '@vueuse/firebase/useFirestore'
13import { initializeApp } from 'firebase/app'
14import { collection, doc, getFirestore, limit, orderBy, query } from 'firebase/firestore'
15import { computed, shallowRef } from 'vue'
16 
17const app = initializeApp({ projectId: 'MY PROJECT ID' })
18const db = getFirestore(app)
19 
20const todos = useFirestore(collection(db, 'todos'))
21 
22// or for doc reference
23const user = useFirestore(doc(db, 'users', 'my-user-id'))
24 
25// you can also use ref value for reactive query
26const postsLimit = shallowRef(10)
27const postsQuery = computed(() => query(collection(db, 'posts'), orderBy('createdAt', 'desc'), limit(postsLimit.value)))
28const posts = useFirestore(postsQuery)
29 
30// you can use the boolean value to tell a query when it is ready to run
31// when it gets falsy value, return the initial value
32const userId = shallowRef('')
33const userQuery = computed(() => userId.value && doc(db, 'users', userId.value))
34const userData = useFirestore(userQuery, null)
35```
36 
37### Return Value
38 
39- For **Document Reference**: Returns `Ref<T | null>` (single document with `id` property)
40- For **Query**: Returns `Ref<T[]>` (array of documents, each with `id` property)
41 
42The document `id` is automatically added as a read-only property to each returned document.
43 
44### Options
45 
46| Option         | Type                   | Default         | Description                                                                |
47| -------------- | ---------------------- | --------------- | -------------------------------------------------------------------------- |
48| `errorHandler` | `(err: Error) => void` | `console.error` | Custom error handler                                                       |
49| `autoDispose`  | `boolean \| number`    | `true`          | Auto-unsubscribe on scope dispose. Pass a number for delayed dispose (ms). |
50 
51### Error Handling
52 
53```ts
54const todos = useFirestore(collection(db, 'todos'), [], {
55  errorHandler: (err) => {
56    console.error('Firestore error:', err)
57    // Handle error (e.g., show notification)
58  },
59})
60```
61 
62## Share across instances
63 
64You can reuse the db reference by passing `autoDispose: false`. You can also set an amount of milliseconds before auto disposing the db reference.
65 
66Note : Getting a not disposed db reference again don't cost a Firestore read.
67 
68```ts
69import { useFirestore } from '@vueuse/firebase/useFirestore'
70import { collection } from 'firebase/firestore'
71// ---cut---
72const todos = useFirestore(collection(db, 'todos'), undefined, { autoDispose: false })
73```
74 
75or use `createGlobalState` from the core package
76 
77```ts twoslash include store
78// @filename: store.ts
79// ---cut---
80// store.ts
81import { createGlobalState } from '@vueuse/core'
82import { useFirestore } from '@vueuse/firebase/useFirestore'
83 
84export const useTodos = createGlobalState(
85  () => useFirestore(collection(db, 'todos')),
86)
87```
88 
89```vue
90<!-- app.vue -->
91<script setup lang="ts">
92// @include: store
93// ---cut---
94import { useTodos } from './store'
95 
96const todos = useTodos()
97</script>
98```
99 
100## Type Declarations
101 
102```ts
103export interface UseFirestoreOptions {
104  errorHandler?: (err: Error) => void
105  autoDispose?: boolean | number
106}
107export type FirebaseDocRef<T> = Query<T> | DocumentReference<T>
108type Falsy = false | 0 | "" | null | undefined
109export declare function useFirestore<T extends DocumentData>(
110  maybeDocRef: MaybeRef<DocumentReference<T> | Falsy>,
111  initialValue: T,
112  options?: UseFirestoreOptions,
113): Ref<T | null>
114export declare function useFirestore<T extends DocumentData>(
115  maybeDocRef: MaybeRef<Query<T> | Falsy>,
116  initialValue: T[],
117  options?: UseFirestoreOptions,
118): Ref<T[]>
119export declare function useFirestore<T extends DocumentData>(
120  maybeDocRef: MaybeRef<DocumentReference<T> | Falsy>,
121  initialValue?: T | undefined | null,
122  options?: UseFirestoreOptions,
123): Ref<T | undefined | null>
124export declare function useFirestore<T extends DocumentData>(
125  maybeDocRef: MaybeRef<Query<T> | Falsy>,
126  initialValue?: T[],
127  options?: UseFirestoreOptions,
128): Ref<T[] | undefined>
129```
130