React-Admin Development Guide

React-admin is a framework for building single-page applications on top of REST/GraphQL APIs. It builds on top of React Query, react-hook-form, react-router, and Material UI. It provides 150+ components and dozens of hooks. Before writing custom code, always check if react-admin already provides a component or hook for the task. Full documentation: https://marmelab.com/react-admin/doc/

Providers (Backend Abstraction)

React-admin never calls APIs directly. All communication goes through providers — adapters that translate react-admin's standardized calls into API-specific requests. The three main providers are:

dataProvider: All CRUD operations (
```
getList
```
,
```
getOne
```
,
```
create
```
,
```
update
```
,
```
delete
```
,
```
getMany
```
,
```
getManyReference
```
,
```
updateMany
```
,
```
deleteMany
```
). See DataProviders and 50+ existing adapters.
authProvider: Authentication and authorization. See Authentication.
i18nProvider: Translations (
```
translate
```
,
```
changeLocale
```
,
```
getLocale
```
).

Critical rule: Never use

fetch

axios

, or direct HTTP calls in components. Always use data provider hooks. This ensures proper caching, loading states, error handling, authentication, and optimistic rendering.

Composition (Not God Components)

React-admin uses composition over configuration. Override behavior by passing child components, not by setting dozens of props:

jsx

<Edit actions={<MyCustomActions />}>
    <SimpleForm>
        <TextInput source="title" />
    </SimpleForm>
</Edit>

To customize the layout, pass a custom layout component to

<Admin layout={MyLayout}>

. To customize the menu, pass it to

<Layout menu={MyMenu}>

. This chaining is by design — see Architecture.

Context: Pull, Don't Push

React-admin components expose data to descendants via React contexts. Access data using hooks rather than passing props down:

```
useRecordContext()
```
— current record in Show/Edit/Create views. See useRecordContext.
```
useListContext()
```
— list data, filters, pagination, sort in List views. See useListContext.

useShowContext()

useEditContext()

useCreateContext()

— page-level state for detail views.

```
useTranslate()
```
— translation function from i18nProvider.
```
useGetIdentity()
```
— current user from authProvider.

Hooks Over Custom Components

When a react-admin component's UI doesn't fit, use the underlying hook instead of building from scratch. Controller hooks (named

use*Controller

) provide all the logic without the UI:

```
useListController()
```
— list fetching, filtering, pagination logic
```
useEditController()
```
— edit form fetching and submission logic
```
useShowController()
```
— show page data fetching logic

Routing

<Resource>

declares CRUD routes automatically (

/posts

/posts/create

/posts/:id/edit

/posts/:id/show

). Use

<CustomRoutes>

for non-CRUD pages. Use

useCreatePath()

to build resource URLs and

<Link>

from react-admin for navigation. Default router is react-router (HashRouter), but TanStack Router is also supported via

routerProvider

. See Routing.

Data Fetching

Query Hooks (Reading Data)

jsx

const { data, total, isPending, error } = useGetList('posts', {
    pagination: { page: 1, perPage: 25 },
    sort: { field: 'created_at', order: 'DESC' },
    filter: { status: 'published' },
});

const { data: record, isPending } = useGetOne('posts', { id: 123 });
const { data: records } = useGetMany('posts', { ids: [1, 2, 3] });
const { data, total } = useGetManyReference('comments', {
    target: 'post_id', id: 123,
    pagination: { page: 1, perPage: 25 },
});

See useGetList, useGetOne.

Mutation Hooks (Writing Data)

All mutations return

[mutate, state]

. They support three mutation modes:

pessimistic (default): Wait for server response, then update UI.
optimistic: Update UI immediately, revert on server error.
undoable: Update UI, show undo notification, commit after delay.

jsx

const [create, { isPending }] = useCreate();
const [update] = useUpdate();
const [deleteOne] = useDelete();

// Call with resource and params
create('posts', { data: { title: 'Hello' } });
update('posts', { id: 1, data: { title: 'Updated' }, previousData: record });
deleteOne('posts', { id: 1, previousData: record });

Pass

mutationMode: 'optimistic'

'undoable'

for instant UI feedback. See useCreate, useUpdate.

Authentication & Authorization

typescript

const authProvider = {
    login: ({ username, password }) => Promise<void>,
    logout: () => Promise<void>,
    checkAuth: () => Promise<void>,           // Verify credentials are valid
    checkError: (error) => Promise<void>,      // Detect auth errors from API responses
    getIdentity: () => Promise<{ id, fullName, avatar }>,
    getPermissions: () => Promise<any>,
    canAccess: ({ resource, action, record }) => Promise<boolean>,  // RBAC
};

Each auth provider method has a corresponding hook (e.g.

useGetIdentity()

useCanAccess()

Custom routes are public by default. Wrap them with
```
<Authenticated>
```
or call
```
useAuthenticated()
```
to require login. See Authenticated.
Centralize authorization in
```
authProvider.canAccess()
```
, not in individual components. Use
```
useCanAccess()
```
to check permissions. See useCanAccess and AuthRBAC.
The dataProvider must include credentials (Bearer token, cookies) in requests — authProvider handles login, but dataProvider handles API calls. Configure
```
httpClient
```
in data provider setup.

Relationships Between Entities

Fetching all the data (including relationships) upfront for a given page is an anti-pattern. Instead, fetch related records on demand using reference fields and inputs.

Displaying Related Records (Fields)

jsx

{/* Show a the company of the current record based on its company_id */}
<ReferenceField source="company_id" reference="companies" />

{/* Show a list of related records (reverse FK) */}
<ReferenceManyField reference="comments" target="post_id">
    <DataTable>
        <TextField source="body" />
        <DateField source="created_at" />
    </DataTable>
</ReferenceManyField>

{/* Show multiple referenced records (array of IDs) */}
<ReferenceArrayField source="tag_ids" reference="tags">
    <SingleFieldList>
        <ChipField source="name" />
    </SingleFieldList>
</ReferenceArrayField>

See ReferenceField, ReferenceManyField, ReferenceArrayField.

Editing Related Records (Inputs)

jsx

{/* Select from another resource (FK) */}
<ReferenceInput source="company_id" reference="companies" />

{/* Multi-select from another resource (array of IDs) */}
<ReferenceArrayInput source="tag_ids" reference="tags" />

See ReferenceInput, ReferenceArrayInput.

Forms

React-admin forms are built on react-hook-form. Use

<SimpleForm>

for single-column layouts and

<TabbedForm>

for multi-tab layouts. See SimpleForm, TabbedForm.

Pass validators to input components:

required()

minLength(min)

maxLength(max)

minValue(min)

maxValue(max)

number()

email()

regex(pattern, message)

, or a custom function returning an error string.

jsx

<TextInput source="title" validate={[required(), minLength(3)]} />

Use RHF's

useWatch()

to create dynamic forms that react to field values:

Resource Definition

Encapsulate resource components in index files for clean imports:

jsx

// posts/index.ts
export default {
    list: PostList,
    create: PostCreate,
    edit: PostEdit,
    icon: PostIcon,
    recordRepresentation: (record) => record.title,  // How records appear in references
};

See Resource, RecordRepresentation.

Custom Data Provider Methods

Extend the dataProvider with domain-specific methods:

jsx

const dataProvider = {
    ...baseDataProvider,
    archivePost: async (id) => { /* custom logic */ },
};
// Call via useDataProvider and useQuery:
// const dp = useDataProvider(); 
// const { data } = useQuery(['archivePost', id], () => dp.archivePost(id));

Persistent Client State (Store)

Use

useStore()

for persistent user preferences (theme, column visibility, saved filters):

jsx

const [theme, setTheme] = useStore('theme', 'light');

See Store.

Notification, Redirect, Refresh

jsx

const notify = useNotify();
const redirect = useRedirect();
const refresh = useRefresh();

notify('Record saved', { type: 'success' });
redirect('list', 'posts');        // Navigate to /posts
redirect('edit', 'posts', 123);   // Navigate to /posts/123
refresh();                         // Invalidate all queries

Deprecations

Use DataTable instead of Datagrid
Prefer
```
<CanAccess>
```
and
```
useCanAccess
```
for authorization checks

react-admin

NPX Install

Tags

SKILL.md Content