Open History to see the last commit
1---
2id: VirtualRowProps
3title: VirtualRowProps
4---
5
6# Interface: VirtualRowProps\<TKey\>
7
8Defined in: [packages/db/src/virtual-props.ts:57](https://github.com/TanStack/db/blob/main/packages/db/src/virtual-props.ts#L57)
9
10Virtual properties available on every row in TanStack DB collections.
11
12These properties are:
13- Computed (not stored in the data model)
14- Read-only (cannot be mutated directly)
15- Available in queries (WHERE, ORDER BY, SELECT)
16- Included when spreading rows (`...user`)
17
18## Examples
19
20```typescript
21// Accessing virtual properties on a row
22const user = collection.get('user-1')
23if (user.$synced) {
24 console.log('No pending local optimistic writes for this row')
25}
26if (user.$origin === 'local') {
27 console.log('Created/modified locally')
28}
29```
30
31```typescript
32// Using virtual properties in queries
33const ordersWithoutLocalWrites = createLiveQueryCollection({
34 query: (q) => q
35 .from({ order: orders })
36 .where(({ order }) => eq(order.$synced, true))
37})
38```
39
40## Type Parameters
41
42### TKey
43
44`TKey` *extends* `string` \| `number` = `string` \| `number`
45
46The type of the row's key (string or number)
47
48## Properties
49
50### $collectionId
51
52```ts
53readonly $collectionId: string;
54```
55
56Defined in: [packages/db/src/virtual-props.ts:101](https://github.com/TanStack/db/blob/main/packages/db/src/virtual-props.ts#L101)
57
58The ID of the source collection this row originated from.
59
60In joins, this can help identify which collection each row came from.
61For live query collections, this is the ID of the upstream collection.
62
63***
64
65### $key
66
67```ts
68readonly $key: TKey;
69```
70
71Defined in: [packages/db/src/virtual-props.ts:93](https://github.com/TanStack/db/blob/main/packages/db/src/virtual-props.ts#L93)
72
73The row's key (primary identifier).
74
75This is the same value returned by `collection.config.getKey(row)`.
76Useful when you need the key in projections or computations.
77
78***
79
80### $origin
81
82```ts
83readonly $origin: VirtualOrigin;
84```
85
86Defined in: [packages/db/src/virtual-props.ts:85](https://github.com/TanStack/db/blob/main/packages/db/src/virtual-props.ts#L85)
87
88Origin of the last confirmed change to this row, from the current client's perspective.
89
90- `'local'`: The change originated from this client
91- `'remote'`: The change was received via sync
92
93For local-only collections, this is always `'local'`.
94For live query collections, this is passed through from the source collection.
95
96***
97
98### $synced
99
100```ts
101readonly $synced: boolean;
102```
103
104Defined in: [packages/db/src/virtual-props.ts:74](https://github.com/TanStack/db/blob/main/packages/db/src/virtual-props.ts#L74)
105
106Whether this row currently has no pending local optimistic writes.
107
108- `true`: No pending local optimistic mutation currently affects this row
109- `false`: One or more pending local optimistic mutations currently affect this row
110
111This is local mutation status. It does not prove that a backend has uploaded,
112confirmed, or read back the row. If you need backend-confirmed status, keep
113your mutation function pending until that backend observation has happened,
114or expose adapter-specific status.
115
116For local-only collections (no sync), this is always `true`.
117For live query collections, this is passed through from the source collection.