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