React Admin

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:

<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)

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.

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' or 'undoable' for instant UI feedback. See useCreate, useUpdate.