0
# Refine Core
1

2
Refine Core is a React meta-framework for building enterprise CRUD applications with authentication, data management, and headless UI integration. It provides a comprehensive set of hooks, components, and utilities for rapid development of data-intensive applications with minimal boilerplate.
3

4
## Package Information
5

6
- **Package Name**: @refinedev/core
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @refinedev/core`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  Refine,
16
  useList,
17
  useOne,
18
  useCreate,
19
  useUpdate,
20
  useDelete,
21
  useForm,
22
  useTable,
23
  useNavigation
24
} from "@refinedev/core";
25
```
26

27
For CommonJS:
28

29
```javascript
30
const { 
31
  Refine,
32
  useList,
33
  useOne,
34
  useCreate,
35
  useUpdate,
36
  useDelete,
37
  useForm,
38
  useTable,
39
  useNavigation
40
} = require("@refinedev/core");
41
```
42

43
## Basic Usage
44

45
```typescript
46
import React from "react";
47
import { Refine, useList, useCreate } from "@refinedev/core";
48
import dataProvider from "@refinedev/simple-rest";
49

50
// App setup with Refine wrapper
51
function App() {
52
  return (
53
    <Refine
54
      dataProvider={dataProvider("https://api.fake-rest.refine.dev")}
55
      resources={[
56
        {
57
          name: "posts",
58
          list: "/posts",
59
          create: "/posts/create",
60
          edit: "/posts/edit/:id",
61
          show: "/posts/show/:id",
62
        },
63
      ]}
64
    >
65
      <PostsList />
66
    </Refine>
67
  );
68
}
69

70
// Component using Refine hooks
71
function PostsList() {
72
  const { data: posts, isLoading } = useList({
73
    resource: "posts",
74
    pagination: { pageSize: 10 }
75
  });
76
  
77
  const { mutate: createPost } = useCreate();
78
  
79
  const handleCreatePost = () => {
80
    createPost({
81
      resource: "posts",
82
      values: {
83
        title: "New Post",
84
        content: "Post content"
85
      }
86
    });
87
  };
88
  
89
  if (isLoading) return <div>Loading...</div>;
90
  
91
  return (
92
    <div>
93
      <button onClick={handleCreatePost}>Create Post</button>
94
      {posts?.data.map(post => (
95
        <div key={post.id}>{post.title}</div>
96
      ))}
97
    </div>
98
  );
99
}
100
```
101

102
## Architecture
103

104
Refine Core is built around several key architectural components:
105

106
- **Provider System**: Pluggable providers for data, authentication, routing, notifications, and access control
107
- **Hook-Based API**: React hooks for all operations, ensuring proper React integration and state management
108
- **Resource-Centric**: Operations are organized around resources (entities) with automatic routing and parameter inference
109
- **Type Safety**: Full TypeScript support with generic types for data structures and operations
110
- **Query Management**: Built on React Query for advanced caching, synchronization, and background updates
111
- **Headless UI**: Core provides logic and state management while being UI framework agnostic
112

113
## Capabilities
114

115
### Application Setup & Core Components
116

117
Main application wrapper and foundational components for setting up Refine applications with providers and resource configuration.
118

119
```typescript { .api }
120
interface RefineProps<TAuthProvider, TDataProvider, TRouterProvider, TNotificationProvider, TAccessControlProvider, TI18nProvider, TLiveProvider, TAuditLogProvider> {
121
  dataProvider: TDataProvider | Record<string, TDataProvider>;
122
  authProvider?: TAuthProvider;
123
  routerProvider?: TRouterProvider;
124
  notificationProvider?: TNotificationProvider;
125
  accessControlProvider?: TAccessControlProvider;
126
  i18nProvider?: TI18nProvider;
127
  liveProvider?: TLiveProvider;
128
  auditLogProvider?: TAuditLogProvider;
129
  resources?: ResourceProps[];
130
  options?: RefineOptions;
131
  children?: React.ReactNode;
132
}
133

134
function Refine<TAuthProvider, TDataProvider, TRouterProvider, TNotificationProvider, TAccessControlProvider, TI18nProvider, TLiveProvider, TAuditLogProvider>(
135
  props: RefineProps<TAuthProvider, TDataProvider, TRouterProvider, TNotificationProvider, TAccessControlProvider, TI18nProvider, TLiveProvider, TAuditLogProvider>
136
): JSX.Element;
137
```
138

139
[Application Setup & Core Components](./application-setup.md)
140

141
### Data Operations & CRUD Hooks
142

143
Comprehensive data management hooks for CRUD operations, custom queries, and real-time data synchronization with built-in caching and state management.
144

145
```typescript { .api }
146
function useList<TQueryFnData = BaseRecord, TError = HttpError, TData = TQueryFnData>(
147
  params?: UseListConfig<TQueryFnData, TError, TData>
148
): UseListReturnType<TData, TError>;
149

150
function useOne<TQueryFnData = BaseRecord, TError = HttpError, TData = TQueryFnData>(
151
  params: UseOneConfig<TQueryFnData, TError, TData>
152
): UseOneReturnType<TData, TError>;
153

154
function useCreate<TData = BaseRecord, TError = HttpError, TVariables = {}>(
155
  params?: UseCreateConfig<TData, TError, TVariables>
156
): UseCreateReturnType<TData, TError, TVariables>;
157

158
function useUpdate<TData = BaseRecord, TError = HttpError, TVariables = {}>(
159
  params?: UseUpdateConfig<TData, TError, TVariables>
160
): UseUpdateReturnType<TData, TError, TVariables>;
161

162
function useDelete<TData = BaseRecord, TError = HttpError>(
163
  params?: UseDeleteConfig<TData, TError>
164
): UseDeleteReturnType<TData, TError>;
165
```
166

167
[Data Operations & CRUD Hooks](./data-operations.md)
168

169
### Authentication & Authorization
170

171
Complete authentication system with login, logout, registration flows, and fine-grained access control for resources and actions.
172

173
```typescript { .api }
174
function useLogin<TData = {}, TError = {}, TVariables = {}>(
175
  params?: UseLoginConfig<TData, TError, TVariables>
176
): UseLoginReturnType<TData, TError, TVariables>;
177

178
function useLogout<TData = {}, TError = {}, TVariables = {}>(
179
  params?: UseLogoutConfig<TData, TError, TVariables>
180
): UseLogoutReturnType<TData, TError, TVariables>;
181

182
function useIsAuthenticated<TData = {}>(
183
  params?: UseIsAuthenticatedConfig<TData>
184
): UseIsAuthenticatedReturnType<TData>;
185

186
function useCan(params: UseCanConfig): UseCanReturnType;
187
```
188

189
[Authentication & Authorization](./authentication.md)
190

191
### Navigation & Routing
192

193
Programmatic navigation, route parsing, and URL generation with resource-aware navigation utilities for CRUD operations.
194

195
```typescript { .api }
196
function useNavigation(): UseNavigationReturnType;
197

198
function useGo(): Go;
199

200
function useParsed(): ParsedParams;
201

202
interface UseNavigationReturnType {
203
  list: (resource: string, type?: HistoryType, meta?: Record<string, unknown>) => void;
204
  create: (resource: string, type?: HistoryType, meta?: Record<string, unknown>) => void;
205
  edit: (resource: string, id: BaseKey, type?: HistoryType, meta?: Record<string, unknown>) => void;
206
  show: (resource: string, id: BaseKey, type?: HistoryType, meta?: Record<string, unknown>) => void;
207
  clone: (resource: string, id: BaseKey, type?: HistoryType, meta?: Record<string, unknown>) => void;
208
  listUrl: (resource: string, meta?: Record<string, unknown>) => string;
209
  createUrl: (resource: string, meta?: Record<string, unknown>) => string;
210
  editUrl: (resource: string, id: BaseKey, meta?: Record<string, unknown>) => string;
211
  showUrl: (resource: string, id: BaseKey, meta?: Record<string, unknown>) => string;
212
  cloneUrl: (resource: string, id: BaseKey, meta?: Record<string, unknown>) => string;
213
}
214
```
215

216
[Navigation & Routing](./navigation.md)
217

218
### Forms & Data Input
219

220
Advanced form management with auto-save, validation, mutation handling, and integration with popular form libraries.
221

222
```typescript { .api }
223
function useForm<TQueryFnData = BaseRecord, TError = HttpError, TVariables = {}, TData = TQueryFnData, TResponse = BaseRecord, TResponseError = HttpError>(
224
  params?: UseFormConfig<TQueryFnData, TError, TVariables, TData, TResponse, TResponseError>
225
): UseFormReturnType<TQueryFnData, TError, TVariables, TData, TResponse, TResponseError>;
226
```
227

228
[Forms & Data Input](./forms.md)
229

230
### Tables & Lists
231

232
Comprehensive table functionality with sorting, filtering, pagination, search, and URL synchronization for data-heavy interfaces.
233

234
```typescript { .api }
235
function useTable<TQueryFnData = BaseRecord, TError = HttpError, TData = TQueryFnData>(
236
  params?: UseTableConfig<TQueryFnData, TError, TData>
237
): UseTableReturnType<TData, TError>;
238

239
function useSelect<TQueryFnData = BaseRecord, TError = HttpError, TData = TQueryFnData>(
240
  params: UseSelectConfig<TQueryFnData, TError, TData>
241
): UseSelectReturnType<TData, TError>;
242
```
243

244
[Tables & Lists](./tables-lists.md)
245

246
### Utilities & Helpers
247

248
Resource management, loading states, metadata handling, notifications, and various utility functions for enhanced development experience.
249

250
```typescript { .api }
251
function useResourceParams(params?: UseResourceParamsConfig): UseResourceParamsReturnType;
252

253
function useLoadingOvertime(params: UseLoadingOvertimeConfig): UseLoadingOvertimeReturnType;
254

255
function useNotification(): UseNotificationReturnType;
256

257
function useModal(): UseModalReturnType;
258

259
function usePublish(): ((event: LiveEvent) => void) | undefined;
260

261
function useSubscription(params: UseSubscriptionConfig): void;
262

263
function useLiveMode(): UseLiveModeReturnType;
264

265
function useMenu(params?: UseMenuConfig): UseMenuReturnType;
266
```
267

268
[Utilities & Helpers](./utilities.md)
269

270
## Types
271

272
```typescript { .api }
273
type BaseKey = string | number;
274

275
interface BaseRecord {
276
  id?: BaseKey;
277
  [key: string]: any;
278
}
279

280
interface HttpError {
281
  message: string;
282
  statusCode: number;
283
  errors?: ValidationErrors;
284
}
285

286
interface Pagination {
287
  current?: number;
288
  pageSize?: number;
289
  mode?: "server" | "client" | "off";
290
}
291

292
type CrudOperators = 
293
  | "eq" | "ne" | "lt" | "gt" | "lte" | "gte"
294
  | "in" | "nin" | "ina" | "nina" | "contains" | "ncontains"
295
  | "containss" | "ncontainss" | "null" | "nnull"
296
  | "between" | "nbetween" | "startswith" | "nstartswith"
297
  | "startswiths" | "nstartswiths" | "endswith" | "nendswith"
298
  | "endswiths" | "nendswiths" | "or" | "and";
299

300
interface CrudFilter {
301
  field: string;
302
  operator: CrudOperators;
303
  value: any;
304
}
305

306
type CrudFilters = CrudFilter[];
307

308
type SortOrder = "asc" | "desc";
309

310
interface CrudSort {
311
  field: string;
312
  order: SortOrder;
313
}
314

315
type CrudSorting = CrudSort[];
316

317
interface GetListResponse<TData = BaseRecord> {
318
  data: TData[];
319
  total: number;
320
}
321

322
interface GetOneResponse<TData = BaseRecord> {
323
  data: TData;
324
}
325

326
interface CreateResponse<TData = BaseRecord> {
327
  data: TData;
328
}
329

330
interface UpdateResponse<TData = BaseRecord> {
331
  data: TData;
332
}
333

334
interface DeleteOneResponse<TData = BaseRecord> {
335
  data: TData;
336
}
337
```