0
# Data Operations & CRUD Hooks
1
2
Comprehensive data management hooks for CRUD operations, custom queries, and real-time data synchronization.
3
4
## Capabilities
5
6
### Query Hooks
7
8
#### useList Hook
9
10
Fetches multiple records from a resource with support for pagination, filtering, sorting, and real-time updates.
11
12
```typescript { .api }
13
/**
14
* Fetches multiple records from a resource with comprehensive query options
15
* @param params - Configuration for the list query
16
* @returns Query result with data and pagination information
17
*/
18
function useList<TQueryFnData = BaseRecord, TError = HttpError, TData = TQueryFnData>(
19
params?: UseListConfig<TQueryFnData, TError, TData>
20
): UseListReturnType<TData, TError>;
21
22
interface UseListConfig<TQueryFnData, TError, TData> {
23
/** Resource name - inferred from route if not provided */
24
resource?: string;
25
/** Pagination configuration */
26
pagination?: Pagination;
27
/** Sorting configuration */
28
sorters?: CrudSorting;
29
/** Filtering configuration */
30
filters?: CrudFilters;
31
/** Additional metadata for the query */
32
meta?: MetaQuery;
33
/** Specific data provider to use */
34
dataProviderName?: string;
35
/** React Query options */
36
queryOptions?: UseQueryOptions<GetListResponse<TQueryFnData>, TError>;
37
/** Success notification configuration */
38
successNotification?: SuccessErrorNotification | false;
39
/** Error notification configuration */
40
errorNotification?: SuccessErrorNotification | false;
41
/** Live mode configuration */
42
liveMode?: LiveModeProps;
43
/** Callback when live event received */
44
onLiveEvent?: (event: LiveEvent) => void;
45
/** Auto-invalidation configuration */
46
invalidates?: Array<string>;
47
/** Override mutation mode */
48
mutationMode?: MutationMode;
49
}
50
51
interface UseListReturnType<TData, TError> {
52
/** React Query result object */
53
query: UseQueryResult<GetListResponse<TData>, TError>;
54
/** Processed result with data and total */
55
result: {
56
data: TData[];
57
total: number | undefined;
58
};
59
}
60
```
61
62
**Usage Example:**
63
64
```typescript
65
import { useList } from "@refinedev/core";
66
67
function PostsList() {
68
const { data: posts, isLoading, error } = useList({
69
resource: "posts",
70
pagination: {
71
current: 1,
72
pageSize: 10,
73
mode: "server"
74
},
75
sorters: [{
76
field: "createdAt",
77
order: "desc"
78
}],
79
filters: [{
80
field: "status",
81
operator: "eq",
82
value: "published"
83
}],
84
meta: {
85
populate: ["author", "category"]
86
}
87
});
88
89
if (isLoading) return <div>Loading...</div>;
90
if (error) return <div>Error: {error.message}</div>;
91
92
return (
93
<div>
94
{posts?.data.map(post => (
95
<article key={post.id}>
96
<h3>{post.title}</h3>
97
<p>{post.content}</p>
98
</article>
99
))}
100
</div>
101
);
102
}
103
```
104
105
#### useOne Hook
106
107
Fetches a single record by its identifier with support for real-time updates and caching.
108
109
```typescript { .api }
110
/**
111
* Fetches a single record by ID
112
* @param params - Configuration for the single record query
113
* @returns Query result with the fetched record
114
*/
115
function useOne<TQueryFnData = BaseRecord, TError = HttpError, TData = TQueryFnData>(
116
params: UseOneConfig<TQueryFnData, TError, TData>
117
): UseOneReturnType<TData, TError>;
118
119
interface UseOneConfig<TQueryFnData, TError, TData> {
120
/** Resource name - inferred from route if not provided */
121
resource?: string;
122
/** Record identifier to fetch */
123
id: BaseKey;
124
/** Additional metadata for the query */
125
meta?: MetaQuery;
126
/** Specific data provider to use */
127
dataProviderName?: string;
128
/** React Query options */
129
queryOptions?: UseQueryOptions<GetOneResponse<TQueryFnData>, TError>;
130
/** Success notification configuration */
131
successNotification?: SuccessErrorNotification | false;
132
/** Error notification configuration */
133
errorNotification?: SuccessErrorNotification | false;
134
/** Live mode configuration */
135
liveMode?: LiveModeProps;
136
/** Callback when live event received */
137
onLiveEvent?: (event: LiveEvent) => void;
138
}
139
140
interface UseOneReturnType<TData, TError> {
141
/** React Query result object */
142
query: UseQueryResult<GetOneResponse<TData>, TError>;
143
}
144
```
145
146
#### useMany Hook
147
148
Fetches multiple records by their identifiers in a single request.
149
150
```typescript { .api }
151
/**
152
* Fetches multiple records by their IDs
153
* @param params - Configuration for the multiple records query
154
* @returns Query result with the fetched records
155
*/
156
function useMany<TQueryFnData = BaseRecord, TError = HttpError, TData = TQueryFnData>(
157
params: UseManyConfig<TQueryFnData, TError, TData>
158
): UseManyReturnType<TData, TError>;
159
160
interface UseManyConfig<TQueryFnData, TError, TData> {
161
/** Resource name - inferred from route if not provided */
162
resource?: string;
163
/** Array of record identifiers to fetch */
164
ids: BaseKey[];
165
/** Additional metadata for the query */
166
meta?: MetaQuery;
167
/** Specific data provider to use */
168
dataProviderName?: string;
169
/** React Query options */
170
queryOptions?: UseQueryOptions<GetManyResponse<TQueryFnData>, TError>;
171
/** Success notification configuration */
172
successNotification?: SuccessErrorNotification | false;
173
/** Error notification configuration */
174
errorNotification?: SuccessErrorNotification | false;
175
/** Live mode configuration */
176
liveMode?: LiveModeProps;
177
/** Callback when live event received */
178
onLiveEvent?: (event: LiveEvent) => void;
179
}
180
181
interface UseManyReturnType<TData, TError> {
182
/** React Query result object */
183
query: UseQueryResult<GetManyResponse<TData>, TError>;
184
}
185
```
186
187
#### useInfiniteList Hook
188
189
Provides infinite scrolling functionality for large datasets with incremental loading.
190
191
```typescript { .api }
192
/**
193
* Provides infinite scrolling/pagination functionality
194
* @param params - Configuration for infinite list query
195
* @returns Infinite query result with pagination controls
196
*/
197
function useInfiniteList<TQueryFnData = BaseRecord, TError = HttpError, TData = TQueryFnData>(
198
params?: UseInfiniteListConfig<TQueryFnData, TError, TData>
199
): UseInfiniteListReturnType<TData, TError>;
200
201
interface UseInfiniteListConfig<TQueryFnData, TError, TData> {
202
/** Resource name */
203
resource?: string;
204
/** Pagination configuration */
205
pagination?: Pagination;
206
/** Sorting configuration */
207
sorters?: CrudSorting;
208
/** Filtering configuration */
209
filters?: CrudFilters;
210
/** Additional metadata */
211
meta?: MetaQuery;
212
/** Data provider name */
213
dataProviderName?: string;
214
/** React Query infinite options */
215
queryOptions?: UseInfiniteQueryOptions<GetListResponse<TQueryFnData>, TError>;
216
/** Success notification */
217
successNotification?: SuccessErrorNotification | false;
218
/** Error notification */
219
errorNotification?: SuccessErrorNotification | false;
220
}
221
222
interface UseInfiniteListReturnType<TData, TError> {
223
/** React Query infinite result */
224
query: UseInfiniteQueryResult<InfiniteData<GetListResponse<TData>>, TError>;
225
/** Flattened data from all pages */
226
data: TData[] | undefined;
227
/** Total count across all pages */
228
total: number | undefined;
229
/** Whether more data can be fetched */
230
hasNextPage: boolean | undefined;
231
/** Function to fetch next page */
232
fetchNextPage: () => void;
233
/** Whether next page is being fetched */
234
isFetchingNextPage: boolean;
235
}
236
```
237
238
### Mutation Hooks
239
240
#### useCreate Hook
241
242
Creates new records with support for optimistic updates, notifications, and cache invalidation.
243
244
```typescript { .api }
245
/**
246
* Creates a new record with mutation handling
247
* @param params - Configuration for the create mutation
248
* @returns Mutation function and state
249
*/
250
function useCreate<TData = BaseRecord, TError = HttpError, TVariables = {}>(
251
params?: UseCreateConfig<TData, TError, TVariables>
252
): UseCreateReturnType<TData, TError, TVariables>;
253
254
interface UseCreateConfig<TData, TError, TVariables> {
255
/** React Query mutation options */
256
mutationOptions?: UseMutationOptions<CreateResponse<TData>, TError, UseCreateParams<TVariables>>;
257
}
258
259
interface UseCreateReturnType<TData, TError, TVariables> {
260
/** Mutation function to execute create */
261
mutate: (params: UseCreateParams<TVariables>, options?: MutationObserverOptions<CreateResponse<TData>, TError, UseCreateParams<TVariables>>) => void;
262
/** Async mutation function */
263
mutateAsync: (params: UseCreateParams<TVariables>, options?: MutationObserverOptions<CreateResponse<TData>, TError, UseCreateParams<TVariables>>) => Promise<CreateResponse<TData>>;
264
/** React Query mutation result */
265
mutation: UseMutationResult<CreateResponse<TData>, TError, UseCreateParams<TVariables>>;
266
}
267
268
interface UseCreateParams<TVariables> {
269
/** Resource name */
270
resource: string;
271
/** Data to create */
272
values: TVariables;
273
/** Additional metadata */
274
meta?: MetaQuery;
275
/** Data provider name */
276
dataProviderName?: string;
277
/** Cache invalidation configuration */
278
invalidates?: Array<string>;
279
/** Success notification */
280
successNotification?: SuccessErrorNotification | false;
281
/** Error notification */
282
errorNotification?: SuccessErrorNotification | false;
283
/** Override mutation mode */
284
mutationMode?: MutationMode;
285
/** Timeout for undoable mutations */
286
undoableTimeout?: number;
287
}
288
```
289
290
**Usage Example:**
291
292
```typescript
293
import { useCreate } from "@refinedev/core";
294
295
function CreatePostForm() {
296
const { mutate: createPost, isLoading } = useCreate();
297
298
const handleSubmit = (values: { title: string; content: string }) => {
299
createPost({
300
resource: "posts",
301
values,
302
successNotification: {
303
message: "Post created successfully!",
304
description: "Your new post has been published.",
305
type: "success"
306
},
307
meta: {
308
populate: ["author"]
309
}
310
});
311
};
312
313
return (
314
<form onSubmit={handleSubmit}>
315
{/* Form fields */}
316
<button type="submit" disabled={isLoading}>
317
{isLoading ? "Creating..." : "Create Post"}
318
</button>
319
</form>
320
);
321
}
322
```
323
324
#### useUpdate Hook
325
326
Updates existing records with optimistic updates and undoable operations.
327
328
```typescript { .api }
329
/**
330
* Updates an existing record with mutation handling
331
* @param params - Configuration for the update mutation
332
* @returns Mutation function and state
333
*/
334
function useUpdate<TData = BaseRecord, TError = HttpError, TVariables = {}>(
335
params?: UseUpdateConfig<TData, TError, TVariables>
336
): UseUpdateReturnType<TData, TError, TVariables>;
337
338
interface UseUpdateConfig<TData, TError, TVariables> {
339
/** React Query mutation options */
340
mutationOptions?: UseMutationOptions<UpdateResponse<TData>, TError, UseUpdateParams<TVariables>>;
341
}
342
343
interface UseUpdateReturnType<TData, TError, TVariables> {
344
/** Mutation function to execute update */
345
mutate: (params: UseUpdateParams<TVariables>, options?: MutationObserverOptions<UpdateResponse<TData>, TError, UseUpdateParams<TVariables>>) => void;
346
/** Async mutation function */
347
mutateAsync: (params: UseUpdateParams<TVariables>, options?: MutationObserverOptions<UpdateResponse<TData>, TError, UseUpdateParams<TVariables>>) => Promise<UpdateResponse<TData>>;
348
/** React Query mutation result */
349
mutation: UseMutationResult<UpdateResponse<TData>, TError, UseUpdateParams<TVariables>>;
350
}
351
352
interface UseUpdateParams<TVariables> {
353
/** Resource name */
354
resource: string;
355
/** Record identifier to update */
356
id: BaseKey;
357
/** Data to update */
358
values: TVariables;
359
/** Additional metadata */
360
meta?: MetaQuery;
361
/** Data provider name */
362
dataProviderName?: string;
363
/** Cache invalidation configuration */
364
invalidates?: Array<string>;
365
/** Success notification */
366
successNotification?: SuccessErrorNotification | false;
367
/** Error notification */
368
errorNotification?: SuccessErrorNotification | false;
369
/** Override mutation mode */
370
mutationMode?: MutationMode;
371
/** Timeout for undoable mutations */
372
undoableTimeout?: number;
373
}
374
```
375
376
#### useDelete Hook
377
378
Deletes records with support for soft delete, confirmations, and undo functionality.
379
380
```typescript { .api }
381
/**
382
* Deletes a record with mutation handling
383
* @param params - Configuration for the delete mutation
384
* @returns Mutation function and state
385
*/
386
function useDelete<TData = BaseRecord, TError = HttpError>(
387
params?: UseDeleteConfig<TData, TError>
388
): UseDeleteReturnType<TData, TError>;
389
390
interface UseDeleteConfig<TData, TError> {
391
/** React Query mutation options */
392
mutationOptions?: UseMutationOptions<DeleteOneResponse<TData>, TError, UseDeleteParams>;
393
}
394
395
interface UseDeleteReturnType<TData, TError> {
396
/** Mutation function to execute delete */
397
mutate: (params: UseDeleteParams, options?: MutationObserverOptions<DeleteOneResponse<TData>, TError, UseDeleteParams>) => void;
398
/** Async mutation function */
399
mutateAsync: (params: UseDeleteParams, options?: MutationObserverOptions<DeleteOneResponse<TData>, TError, UseDeleteParams>) => Promise<DeleteOneResponse<TData>>;
400
/** React Query mutation result */
401
mutation: UseMutationResult<DeleteOneResponse<TData>, TError, UseDeleteParams>;
402
}
403
404
interface UseDeleteParams {
405
/** Resource name */
406
resource: string;
407
/** Record identifier to delete */
408
id: BaseKey;
409
/** Additional metadata */
410
meta?: MetaQuery;
411
/** Data provider name */
412
dataProviderName?: string;
413
/** Cache invalidation configuration */
414
invalidates?: Array<string>;
415
/** Success notification */
416
successNotification?: SuccessErrorNotification | false;
417
/** Error notification */
418
errorNotification?: SuccessErrorNotification | false;
419
/** Override mutation mode */
420
mutationMode?: MutationMode;
421
/** Timeout for undoable mutations */
422
undoableTimeout?: number;
423
}
424
```
425
426
### Bulk Operations
427
428
#### useCreateMany Hook
429
430
Creates multiple records in a single operation for batch processing.
431
432
```typescript { .api }
433
/**
434
* Creates multiple records in batch
435
* @param params - Configuration for the bulk create mutation
436
* @returns Mutation function and state for bulk creation
437
*/
438
function useCreateMany<TData = BaseRecord, TError = HttpError, TVariables = {}>(
439
params?: UseCreateManyConfig<TData, TError, TVariables>
440
): UseCreateManyReturnType<TData, TError, TVariables>;
441
442
interface UseCreateManyParams<TVariables> {
443
/** Resource name */
444
resource: string;
445
/** Array of data to create */
446
values: TVariables[];
447
/** Additional metadata */
448
meta?: MetaQuery;
449
/** Data provider name */
450
dataProviderName?: string;
451
/** Cache invalidation configuration */
452
invalidates?: Array<string>;
453
/** Success notification */
454
successNotification?: SuccessErrorNotification | false;
455
/** Error notification */
456
errorNotification?: SuccessErrorNotification | false;
457
}
458
```
459
460
#### useUpdateMany Hook
461
462
Updates multiple records by their identifiers in a single operation.
463
464
```typescript { .api }
465
/**
466
* Updates multiple records in batch
467
* @param params - Configuration for the bulk update mutation
468
* @returns Mutation function and state for bulk updates
469
*/
470
function useUpdateMany<TData = BaseRecord, TError = HttpError, TVariables = {}>(
471
params?: UseUpdateManyConfig<TData, TError, TVariables>
472
): UseUpdateManyReturnType<TData, TError, TVariables>;
473
474
interface UseUpdateManyParams<TVariables> {
475
/** Resource name */
476
resource: string;
477
/** Array of record identifiers to update */
478
ids: BaseKey[];
479
/** Data to update */
480
values: TVariables;
481
/** Additional metadata */
482
meta?: MetaQuery;
483
/** Data provider name */
484
dataProviderName?: string;
485
/** Cache invalidation configuration */
486
invalidates?: Array<string>;
487
/** Success notification */
488
successNotification?: SuccessErrorNotification | false;
489
/** Error notification */
490
errorNotification?: SuccessErrorNotification | false;
491
}
492
```
493
494
#### useDeleteMany Hook
495
496
Deletes multiple records by their identifiers in a single operation.
497
498
```typescript { .api }
499
/**
500
* Deletes multiple records in batch
501
* @param params - Configuration for the bulk delete mutation
502
* @returns Mutation function and state for bulk deletion
503
*/
504
function useDeleteMany<TData = BaseRecord, TError = HttpError>(
505
params?: UseDeleteManyConfig<TData, TError>
506
): UseDeleteManyReturnType<TData, TError>;
507
508
interface UseDeleteManyParams {
509
/** Resource name */
510
resource: string;
511
/** Array of record identifiers to delete */
512
ids: BaseKey[];
513
/** Additional metadata */
514
meta?: MetaQuery;
515
/** Data provider name */
516
dataProviderName?: string;
517
/** Cache invalidation configuration */
518
invalidates?: Array<string>;
519
/** Success notification */
520
successNotification?: SuccessErrorNotification | false;
521
/** Error notification */
522
errorNotification?: SuccessErrorNotification | false;
523
}
524
```
525
526
### Custom Data Operations
527
528
#### useCustom Hook
529
530
Executes custom API queries that don't fit standard CRUD patterns.
531
532
```typescript { .api }
533
/**
534
* Executes custom API queries
535
* @param params - Configuration for custom query
536
* @returns Query result with custom data
537
*/
538
function useCustom<TQueryFnData = BaseRecord, TError = HttpError, TData = TQueryFnData>(
539
params: UseCustomConfig<TQueryFnData, TError, TData>
540
): UseCustomReturnType<TData, TError>;
541
542
interface UseCustomConfig<TQueryFnData, TError, TData> {
543
/** Custom URL endpoint */
544
url: string;
545
/** HTTP method */
546
method: "get" | "delete" | "head" | "options" | "post" | "put" | "patch";
547
/** Additional configuration */
548
config?: {
549
/** Request headers */
550
headers?: Record<string, string>;
551
/** URL query parameters */
552
query?: Record<string, any>;
553
/** Request payload */
554
payload?: Record<string, any>;
555
/** Request filters */
556
filters?: CrudFilters;
557
/** Request sorters */
558
sorters?: CrudSorting;
559
/** Pagination */
560
pagination?: Pagination;
561
};
562
/** Additional metadata */
563
meta?: MetaQuery;
564
/** Data provider name */
565
dataProviderName?: string;
566
/** React Query options */
567
queryOptions?: UseQueryOptions<CustomResponse<TQueryFnData>, TError>;
568
/** Success notification */
569
successNotification?: SuccessErrorNotification | false;
570
/** Error notification */
571
errorNotification?: SuccessErrorNotification | false;
572
}
573
574
interface UseCustomReturnType<TData, TError> {
575
/** React Query result */
576
query: UseQueryResult<CustomResponse<TData>, TError>;
577
}
578
579
interface CustomResponse<TData> {
580
data: TData;
581
}
582
```
583
584
#### useCustomMutation Hook
585
586
Executes custom API mutations for non-standard operations.
587
588
```typescript { .api }
589
/**
590
* Executes custom API mutations
591
* @param params - Configuration for custom mutation
592
* @returns Mutation function and state
593
*/
594
function useCustomMutation<TData = BaseRecord, TError = HttpError, TVariables = {}>(
595
params?: UseCustomMutationConfig<TData, TError, TVariables>
596
): UseCustomMutationReturnType<TData, TError, TVariables>;
597
598
interface UseCustomMutationConfig<TData, TError, TVariables> {
599
/** React Query mutation options */
600
mutationOptions?: UseMutationOptions<CustomResponse<TData>, TError, UseCustomMutationParams<TVariables>>;
601
}
602
603
interface UseCustomMutationParams<TVariables> {
604
/** Custom URL endpoint */
605
url: string;
606
/** HTTP method */
607
method: "get" | "delete" | "head" | "options" | "post" | "put" | "patch";
608
/** Request configuration */
609
config?: {
610
/** Request headers */
611
headers?: Record<string, string>;
612
/** Request payload */
613
payload?: TVariables;
614
};
615
/** Additional metadata */
616
meta?: MetaQuery;
617
/** Data provider name */
618
dataProviderName?: string;
619
/** Success notification */
620
successNotification?: SuccessErrorNotification | false;
621
/** Error notification */
622
errorNotification?: SuccessErrorNotification | false;
623
}
624
```
625
626
### Data Provider Utilities
627
628
#### useDataProvider Hook
629
630
Provides direct access to the data provider instance for advanced operations.
631
632
```typescript { .api }
633
/**
634
* Gets access to the data provider instance
635
* @returns Data provider instance or provider map
636
*/
637
function useDataProvider(): DataProviderResult;
638
639
type DataProviderResult = DataProvider | Record<string, DataProvider>;
640
```
641
642
#### useApiUrl Hook
643
644
Generates the base API URL for a specific resource using the data provider.
645
646
```typescript { .api }
647
/**
648
* Gets the API URL for a resource
649
* @param params - Configuration for API URL generation
650
* @returns Query result with the API URL
651
*/
652
function useApiUrl(params?: UseApiUrlConfig): UseApiUrlReturnType;
653
654
interface UseApiUrlConfig {
655
/** Data provider name */
656
dataProviderName?: string;
657
}
658
659
interface UseApiUrlReturnType {
660
/** Query result with API URL */
661
query: UseQueryResult<string, Error>;
662
}
663
```
664
665
## Types
666
667
```typescript { .api }
668
interface MetaQuery {
669
[key: string]: any;
670
}
671
672
interface SuccessErrorNotification {
673
message: string;
674
description?: string;
675
type: "success" | "error" | "progress";
676
}
677
678
interface LiveEvent {
679
channel: string;
680
type: "created" | "updated" | "deleted";
681
payload: {
682
ids?: BaseKey[];
683
[key: string]: any;
684
};
685
date: Date;
686
}
687
688
interface GetListParams {
689
resource: string;
690
pagination?: Pagination;
691
sorters?: CrudSorting;
692
filters?: CrudFilters;
693
meta?: MetaQuery;
694
}
695
696
interface GetOneParams {
697
resource: string;
698
id: BaseKey;
699
meta?: MetaQuery;
700
}
701
702
interface GetManyParams {
703
resource: string;
704
ids: BaseKey[];
705
meta?: MetaQuery;
706
}
707
708
interface CreateParams<TVariables> {
709
resource: string;
710
variables: TVariables;
711
meta?: MetaQuery;
712
}
713
714
interface UpdateParams<TVariables> {
715
resource: string;
716
id: BaseKey;
717
variables: TVariables;
718
meta?: MetaQuery;
719
}
720
721
interface DeleteOneParams {
722
resource: string;
723
id: BaseKey;
724
meta?: MetaQuery;
725
}
726
727
interface CustomParams {
728
url: string;
729
method: "get" | "delete" | "head" | "options" | "post" | "put" | "patch";
730
filters?: CrudFilters;
731
sorters?: CrudSorting;
732
pagination?: Pagination;
733
payload?: Record<string, any>;
734
query?: Record<string, any>;
735
headers?: Record<string, string>;
736
meta?: MetaQuery;
737
}
738
```