Querying the API

Admin interfaces often have to query the API beyond CRUD requests. For instance, a user profile page may need to get the User object based on a user id. Or, users may want to “Approve” a comment by pressing a button, and this action should update the is_approved property and save the updated record in one click.

React-admin provides special hooks to emit read and write queries to the dataProvider, which in turn sends requests to your API.

useDataProvider Hook

React-admin stores the dataProvider object in a React context, so it’s available from anywhere in your application code. The useDataProvider hook exposes the Data Provider to let you call it directly.

For instance, here is how to query the Data Provider for the current user profile:

import * as React from 'react';
import { useState, useEffect } from 'react';
import { useDataProvider, Loading, Error } from 'react-admin';

const UserProfile = ({ userId }) => {
    const dataProvider = useDataProvider();
    const [user, setUser] = useState();
    const [loading, setLoading] = useState(true);
    const [error, setError] = useState();
    useEffect(() => {
        dataProvider.getOne('users', { id: userId })
            .then(({ data }) => {
                setUser(data);
                setLoading(false);
            })
            .catch(error => {
                setError(error);
                setLoading(false);
            })
    }, []);

    if (loading) return <Loading />;
    if (error) return <Error />;
    if (!user) return null;

    return (
        <ul>
            <li>Name: {user.name}</li>
            <li>Email: {user.email}</li>
        </ul>
    )
};

Tip: The dataProvider returned by the hook is actually a wrapper around your Data Provider. This wrapper updates the Redux store on success, and keeps track of the loading state. In case you don’t want to update the Redux store (e.g. when implementing an autosave feature), you should access the raw, non-wrapped Data Provider from the DataProviderContext:

import * as React from 'react';
-import { useState, useEffect } from 'react';
+import { useState, useEffect, useContext } from 'react';
-import { useDataProvider, Loading, Error } from 'react-admin';
+import { DataProviderContext, Loading, Error } from 'react-admin';

const UserProfile = ({ userId }) => {
-   const dataProvider = useDataProvider();
+   const dataProvider = useContext(DataProviderContext);
    const [user, setUser] = useState();
    const [loading, setLoading] = useState(true);
    const [error, setError] = useState();
    useEffect(() => {
        dataProvider.getOne('users', { id: userId })
            .then(({ data }) => {
                setUser(data);
                setLoading(false);
            })
            .catch(error => {
                setError(error);
                setLoading(false);
            })
    }, []);

    if (loading) return <Loading />;
    if (error) return <Error />;
    if (!user) return null;

    return (
        <ul>
            <li>Name: {user.name}</li>
            <li>Email: {user.email}</li>
        </ul>
    )
};

Tip: If you use TypeScript, you can specify a record type for more type safety:

dataProvider.getOne<Product>('users', { id: 123 })
    .then(({ data }) => {
        //     \- type of data is Product
        // ...
    })

useQuery Hook

The useQuery hook calls the Data Provider on mount, and returns an object that updates as the response arrives. It reduces the boilerplate code for calling the Data Provider.

For instance, the previous code snippet can be rewritten with useQuery as follows:

import * as React from "react";
import { useQuery, Loading, Error } from 'react-admin';

const UserProfile = ({ userId }) => {
    const { data, loading, error } = useQuery({ 
        type: 'getOne',
        resource: 'users',
        payload: { id: userId }
    });

    if (loading) return <Loading />;
    if (error) return <Error />;
    if (!data) return null;

    return (
        <ul>
            <li>Name: {data.name}</li>
            <li>Email: {data.email}</li>
        </ul>
    )
};

useQuery expects a Query argument with the following keys:

• type: The method to call on the Data Provider, e.g. getList
• resource: The Resource name, e.g. “posts”
• payload: The query parameters. Depends on the query type.

The return value of useQuery is an object representing the query state, using the following keys:

• data: undefined until the response arrives, then contains the data key in the dataProvider response
• total: null until the response arrives, then contains the total key in the dataProvider response (only for getList and getManyReference types)
• error: null unless the dataProvider threw an error, in which case it contains that error.
• loading: A boolean updating according to the request state
• loaded: A boolean updating according to the request state
• refetch: A function you can call to trigger a refetch. It’s different from the refresh function returned by useRefresh as it won’t trigger a refresh of the view, only this specific query.

This object updates according to the request state:

• start: { loading: true, loaded: false, refetch }
• success: { data: [data from response], total: [total from response], loading: false, loaded: true, refetch }
• error: { error: [error from response], loading: false, loaded: false, refetch }

As a reminder, here are the read query types handled by Data Providers:

useQueryWithStore Hook

React-admin exposes a more powerful version of useQuery. useQueryWithStore persist the response from the dataProvider in the internal react-admin Redux store, so that result remains available if the hook is called again in the future.

You can use this hook to show the cached result immediately on mount, while the updated result is fetched from the API. This is called optimistic rendering.

import * as React from "react";
-import { useQuery, Loading, Error } from 'react-admin';
+import { useQueryWithStore, Loading, Error } from 'react-admin';

const UserProfile = ({ record }) => {
-   const { loaded, error, data } = useQuery({
+   const { loaded, error, data } = useQueryWithStore({
        type: 'getOne',
        resource: 'users',
        payload: { id: record.id }
    });
    if (!loaded) { return <Loading />; }
    if (error) { return <Error />; }
    return <div>User {data.username}</div>;
};

In practice, react-admin uses useQueryWithStore instead of useQuery everywhere, and you should probably do the same in your components. It really improves the User Experience, with only one little drawback: if the data changed on the backend side between two calls for the same query, the user may briefly see outdated data before the screen updates with the up-to-date data.

Just like useQuery, useQueryWithStore also returns a refetch function you can call to trigger a refetch. It’s different from the refresh function returned by useRefresh as it won’t trigger a refresh of the view, only this specific query.

useMutation Hook

useQuery emits the request to the dataProvider as soon as the component mounts. To emit the request based on a user action, use the useMutation hook instead. This hook takes the same arguments as useQuery, but returns a callback that emits the request when executed.

Here is an implementation of an “Approve” button:

import * as React from "react";
import { useMutation, Button } from 'react-admin';

const ApproveButton = ({ record }) => {
    const [approve, { loading }] = useMutation({
        type: 'update',
        resource: 'comments',
        payload: { id: record.id, data: { isApproved: true } }
    });
    return <Button label="Approve" onClick={approve} disabled={loading} />;
};

useMutation expects a Query argument with the following keys:

• type: The method to call on the Data Provider, e.g. update
• resource: The Resource name, e.g. “posts”
• payload: The query parameters. Depends on the query type.

The return value of useMutation is an array with the following items:

• A callback function
• An object representing the query state, using the following keys
  • data: undefined until the response arrives, then contains the data key in the dataProvider response
  • error: null unless the dataProvider threw an error, in which case it contains that error.
  • loading: A boolean updating according to the request state
  • loaded: A boolean updating according to the request state

This object updates according to the request state:

• mount: { loading: false, loaded: false }
• mutate called: { loading: true, loaded: false }
• success: { data: [data from response], total: [total from response], loading: false, loaded: true }
• error: { error: [error from response], loading: false, loaded: false }

You can destructure the return value of the useMutation hook as [mutate, { data, total, error, loading, loaded }].

As a reminder, here are the write query types handled by data providers:

useMutation accepts a variant call where the parameters are passed to the callback instead of when calling the hook. Use this variant when some parameters are only known at call time.

import * as React from "react";
import { useMutation, Button } from 'react-admin';

const ApproveButton = ({ record }) => {
    const [mutate, { loading }] = useMutation();
    const approve = event => mutate({
        type: 'update',
        resource: 'comments',
        payload: {
            id: event.target.dataset.id,
            data: { isApproved: true, updatedAt: new Date() }
        },
    });
    return <Button
        label="Approve"
        onClick={approve}
        disabled={loading}
    />;
};

Tip: In the example above, the callback returned by useMutation accepts a Query parameter. But in the previous example, it was called with a DOM Event as parameter (because it was passed directly as onClick handler). useMutation is smart enough to ignore a call time argument if it’s an instance of Event.

Tip: User actions usually trigger write queries - that’s why this hook is called useMutation.

Specialized Hooks

React-admin provides one hook for each of the Data Provider methods. Based on useQuery and useMutation, they are useful shortcuts that make your code more readable and more robust (no more method name passed as string).

For instance, here is an example using useUpdate():

import * as React from "react";
import { useUpdate, Button } from 'react-admin';

const ApproveButton = ({ record }) => {
    const [approve, { loading }] = useUpdate('comments', record.id, { isApproved: true }, record);
    return <Button label="Approve" onClick={approve} disabled={loading} />;
};

The specialized hooks based on useQuery (useGetList, useGetOne, useGetMany, useGetManyReference) execute on mount. The specialized hooks based on useMutation (useCreate, useUpdate, useUpdateMany, useDelete, useDeleteMany) return a callback.

Tip: If you use TypeScript, you can specify the record type for more type safety:

const { data, loaded } = useGetOne<Product>('products', 123);
//        \- type of data is Product

useGetList

// syntax
const { data, ids, total, loading, loaded, error, refetch } = useGetList(resource, pagination, sort, filter, options);

// example
import { useGetList } from 'react-admin';
const LatestNews = () => {
    const { data, ids, loading, error } = useGetList(
        'posts',
        { page: 1, perPage: 10 },
        { field: 'published_at', order: 'DESC' }
    );
    if (loading) { return <Loading />; }
    if (error) { return <p>ERROR</p>; }
    return (
        <ul>
            {ids.map(id =>
                <li key={id}>{data[id].title}</li>
            )}
        </ul>
    );
};

useGetOne

// syntax
const { data, loading, loaded, error, refetch } = useGetOne(resource, id, options);

// example
import { useGetOne } from 'react-admin';
const UserProfile = ({ record }) => {
    const { data, loading, error } = useGetOne('users', record.id);
    if (loading) { return <Loading />; }
    if (error) { return <p>ERROR</p>; }
    return <div>User {data.username}</div>;
};

useGetMany

// syntax
const { data, loading, loaded, error, refetch } = useGetMany(resource, ids, options);

// example
import { useGetMany } from 'react-admin';
const PostTags = ({ record }) => {
    const { data, loading, error } = useGetMany('tags', record.tagIds);
    if (loading) { return <Loading />; }
    if (error) { return <p>ERROR</p>; }
    return (
         <ul>
             {data.map(tag => (
                 <li key={tag.id}>{tag.name}</li>
             ))}
         </ul>
     );
};

useGetManyReference

// syntax
const { data, ids, total, loading, loaded, error, refetch } = useGetManyReference(resource, target, id, pagination, sort, filter, referencingResource, options);

// example
import { useGetManyReference } from 'react-admin';
const PostComments = ({ post_id }) => {
    const { data, ids, loading, error } = useGetManyReference(
        'comments',
        'post_id',
        post_id,
        { page: 1, perPage: 10 },
        { field: 'published_at', order: 'DESC' },
        {},
        'posts',
    );
    if (loading) { return <Loading />; }
    if (error) { return <p>ERROR</p>; }
    return (
        <ul>
            {ids.map(id =>
                <li key={id}>{data[id].body}</li>
            )}
        </ul>
    );
};

useCreate

// syntax
const [create, { data, loading, loaded, error }] = useCreate(resource, data, options);

The create() function can be called in 3 different ways:

• with the same parameters as the useCreate() hook: create(resource, data, options)
• with the same syntax as useMutation: create({ resource, payload: { data } }, options)
• with no parameter (if they were already passed to useCreate()): create()

// set params when calling the update callback
import { useCreate } from 'react-admin';

const LikeButton = ({ record }) => {
    const like = { postId: record.id };
    const [create, { loading, error }] = useCreate();
    const handleClick = () => {
        create('likes', like)
    }
    if (error) { return <p>ERROR</p>; }
    return <button disabled={loading} onClick={handleClick}>Like</button>;
};

// set params when calling the hook
import { useCreate } from 'react-admin';

const LikeButton = ({ record }) => {
    const like = { postId: record.id };
    const [create, { loading, error }] = useCreate('likes', like);
    if (error) { return <p>ERROR</p>; }
    return <button disabled={loading} onClick={create}>Like</button>;
};

useUpdate

// syntax
const [update, { data, loading, loaded, error }] = useUpdate(resource, id, data, previousData, options);

The update() method can be called in 3 different ways:

• with the same parameters as the useUpdate() hook: update(resource, id, data, previousData, options)
• with the same syntax as useMutation: update({ resource, payload: { id, data, previousData } }, options)
• with no parameter (if they were already passed to useUpdate()): update()

// set params when calling the update callback
import { useUpdate } from 'react-admin';

const IncreaseLikeButton = ({ record }) => {
    const diff = { likes: record.likes + 1 };
    const [update, { loading, error }] = useUpdate();
    const handleClick = () => {
        update('likes', record.id, diff, record)
    }
    if (error) { return <p>ERROR</p>; }
    return <button disabled={loading} onClick={handleClick}>Like</button>;
};

// or set params when calling the hook
import { useUpdate } from 'react-admin';

const IncreaseLikeButton = ({ record }) => {
    const diff = { likes: record.likes + 1 };
    const [update, { loading, error }] = useUpdate('likes', record.id, diff, record);
    if (error) { return <p>ERROR</p>; }
    return <button disabled={loading} onClick={update}>Like</button>;
};

useUpdateMany

// syntax
const [updateMany, { data, loading, loaded, error }] = useUpdateMany(resource, ids, data, options);

The updateMany() function can be called in 3 different ways:

• with the same parameters as the useUpdateMany() hook: update(resource, ids, data, options)
• with the same syntax as useMutation: update({ resource, payload: { ids, data } }, options)
• with no parameter (if they were already passed to useUpdateMany()): updateMany()

// set params when calling the updateMany callback
import { useUpdateMany } from 'react-admin';

const BulkResetViewsButton = ({ selectedIds }) => {
    const [updateMany, { loading, error }] = useUpdateMany();
    const handleClick = () => {
        updateMany('posts', selectedIds, { views: 0 });
    }
    if (error) { return <p>ERROR</p>; }
    return <button disabled={loading} onClick={handleClick}>Reset views</button>;
};

// set params when calling the hook
import { useUpdateMany } from 'react-admin';

const BulkResetViewsButton = ({ selectedIds }) => {
    const [updateMany, { loading, error }] = useUpdateMany('posts', selectedIds, { views: 0 });
    if (error) { return <p>ERROR</p>; }
    return <button disabled={loading} onClick={updateMany}>Reset views</button>;
};

useDelete

// syntax
const [deleteOne, { data, loading, loaded, error }] = useDelete(resource, id, previousData, options);

The deleteOne() function can be called in 3 different ways:

• with the same parameters as the useDelete() hook: deleteOne(resource, id, previousData, options)
• with the same syntax as useMutation: deleteOne({ resource, payload: { id, previousData } }, options)
• with no parameter (if they were already passed to useDelete()): deleteOne()

// set params when calling the deleteOne callback
import { useDelete } from 'react-admin';

const DeleteButton = ({ record }) => {
    const [deleteOne, { loading, error }] = useDelete();
    const handleClick = () => {
        deleteOne('likes', record.id, record)
    }
    if (error) { return <p>ERROR</p>; }
    return <button disabled={loading} onClick={handleClick}>Delete</button>;
};

// set params when calling the hook
import { useDelete } from 'react-admin';

const DeleteButton = ({ record }) => {
    const [deleteOne, { loading, error }] = useDelete('likes', record.id, record);
    if (error) { return <p>ERROR</p>; }
    return <button disabled={loading} onClick={deleteOne}>Delete</button>;
};

useDeleteMany

// syntax
const [deleteMany, { data, loading, loaded, error }] = useDeleteMany(resource, ids, options);

The deleteMany() function can be called in 3 different ways:

• with the same parameters as the useDeleteMany() hook: deleteMany(resource, ids, options)
• with the same syntax as useMutation: deleteMany({ resource, payload: { ids } }, options)
• with no parameter (if they were already passed to useDeleteMany()): deleteMany()

// set params when calling the dleteMany callback
import { useDeleteMany } from 'react-admin';

const BulkDeletePostsButton = ({ selectedIds }) => {
    const [deleteMany, { loading, error }] = useDeleteMany();
    const handleClick = () => {
        deleteMany('posts', selectedIds)
    }
    if (error) { return <p>ERROR</p>; }
    return <button disabled={loading} onClick={deleteMany}>Delete selected posts</button>;
};

// set params when calling the hook
import { useDeleteMany } from 'react-admin';

const BulkDeletePostsButton = ({ selectedIds }) => {
    const [deleteMany, { loading, error }] = useDeleteMany('posts', selectedIds);
    if (error) { return <p>ERROR</p>; }
    return <button disabled={loading} onClick={deleteMany}>Delete selected posts</button>;
};

Synchronizing Dependant Queries

useQuery and all its corresponding specialized hooks support an enabled option. This is useful if you need to have a query executed only when a condition is met. For example, in the following example, we only fetch the categories if we have at least one post:

// fetch posts
const { ids, data: posts, loading: isLoading } = useGetList(
    'posts',
    { page: 1, perPage: 20 },
    { field: 'name', order: 'ASC' },
    {}
);

// then fetch categories for these posts
const { data: categories, loading: isLoadingCategories } = useGetMany(
    'categories',
    ids.map(id=> posts[id].category_id),
    // run only if the first query returns non-empty result
    { enabled: ids.length > 0 }
);

Handling Side Effects In useDataProvider

useDataProvider returns a dataProvider object. Each call to its method return a Promise, allowing adding business logic on success in then(), and on failure in catch().

For instance, here is another version of the <ApproveButton> based on useDataProvider that notifies the user of success or failure using the bottom notification banner:

import * as React from "react";
import { useDataProvider, useNotify, useRedirect, Button } from 'react-admin';

const ApproveButton = ({ record }) => {
    const notify = useNotify();
    const redirect = useRedirect();
    const dataProvider = useDataProvider();
    const approve = () => dataProvider
        .update('comments', { id: record.id, data: { isApproved: true } })
        .then(response => {
            // success side effects go here
            redirect('/comments');
            notify('Comment approved');
        })
        .catch(error => {
            // failure side effects go here 
            notify(`Comment approval error: ${error.message}`, { type: 'warning' });
        });
    
    return <Button label="Approve" onClick={approve} disabled={loading} />;
};

Fetching data is called a side effect, since it calls the outside world, and is asynchronous. Usual actions may have other side effects, like showing a notification, or redirecting the user to another page. React-admin provides the following hooks to handle most common side effects:

• useNotify: Return a function to display a notification.
• useRedirect: Return a function to redirect the user to another page.
• useRefresh: Return a function to force a rerender of the current view (equivalent to pressing the Refresh button).
• useUnselectAll: Return a function to unselect all lines in the current Datagrid.

useNotify

This hook returns a function that displays a notification in the bottom of the page.

import { useNotify } from 'react-admin';

const NotifyButton = () => {
    const notify = useNotify();
    const handleClick = () => {
        notify(`Comment approved`, { type: 'success' });
    }
    return <button onClick={handleClick}>Notify</button>;
};

The callback takes 6 arguments:

• The message to display
• The level of the notification (info, success or warning - the default is info)
• An options object to pass to the translate function (because notification messages are translated if your admin has an i18nProvider). It is useful for inserting variables into the translation.
• An undoable boolean. Set it to true if the notification should contain an “undo” button
• A duration number. Set it to 0 if the notification should not be dismissible.
• A multiLine boolean. Set it to true if the notification message should be shown in more than one line.

Here are more examples of useNotify calls:

// notify a warning
notify(`This is a warning`, 'warning');
// pass translation arguments
notify('item.created', 'info', { resource: 'post' });
// send an undoable notification
notify('Element updated', 'info', undefined, true);

Tip: The callback also allows a signature with only 2 arguments, the message to display and an object with the rest of the arguments

// notify an undoable success message, with translation arguments
notify('Element deleted', {
    type: 'success',
    undoable: true,
    messageArgs: { resource: 'post' }
});

Tip: When using useNotify as a side effect for an undoable Edit form, you MUST set the fourth argument to true, otherwise the “undo” button will not appear, and the actual update will never occur.

import * as React from 'react';
import { useNotify, Edit, SimpleForm } from 'react-admin';

const PostEdit = props => {
    const notify = useNotify();

    const onSuccess = () => {
        notify('Changes saved`', { undoable: true });
    };

    return (
        <Edit undoable onSuccess={onSuccess} {...props}>
            <SimpleForm>
                ...
            </SimpleForm>
        </Edit>
    );
}

useRedirect

This hook returns a function that redirects the user to another page.

import { useRedirect } from 'react-admin';

const DashboardButton = () => {
    const redirect = useRedirect();
    const handleClick = () => {
        redirect('/dashboard');
    }
    return <button onClick={handleClick}>Dashboard</button>;
};

The callback takes 5 arguments:

• The page to redirect the user to (‘list’, ‘create’, ‘edit’, ‘show’, a function or a custom path)
• The current basePath
• The id of the record to redirect to (if any)
• A record like object to be passed to the first argument, when the first argument is a function
• A state to be set to the location

Here are more examples of useRedirect calls:

// redirect to the post list page
redirect('list', '/posts');
// redirect to the edit page of a post:
redirect('edit', '/posts', 1);
// redirect to the post creation page:
redirect('create', '/posts');
// redirect to the result of a function
redirect((redirectTo, basePath, id, data) => { 
    return  data.hasComments ? '/comments' : '/posts';
}, '/posts', 1, { hasComments: true });
// redirect to edit view with state data
redirect('edit', '/posts', 1, {}, { record: { post_id: record.id } });
// do not redirect (resets the record form)
redirect(false);

Note that useRedirect allows redirection to an absolute url outside the current React app.

useRefresh

This hook returns a function that forces a rerender of the current view.

import { useRefresh } from 'react-admin';

const RefreshButton = () => {
    const refresh = useRefresh();
    const handleClick = () => {
        refresh();
    }
    return <button onClick={handleClick}>Refresh</button>;
};

To make this work, react-admin stores a version number in its state. The useDataProvider() hook uses this version in its effect dependencies. Also, page components use the version as key. The refresh callback increases the version, which forces a re-execution all queries based on the useDataProvider() hook, and a rerender of all components using the version as key.

This means that you can make any component inside a react-admin app refreshable by using the right key:

import * as React from 'react';
import { useVersion } from 'react-admin';

const MyComponent = () => {
    const version = useVersion();
    return <div key={version}>
        ...
    </div>;
};

The callback takes 1 argument:

• hard: when set to true, the callback empties the cache, too

useUnselectAll

This hook returns a function that unselects all lines in the current Datagrid. Pass the name of the resource as argument.

import { useUnselectAll } from 'react-admin';

const UnselectAllButton = () => {
    const unselectAll = useUnselectAll();
    const handleClick = () => {
        unselectAll('posts');
    }
    return <button onClick={handleClick}>Unselect all</button>;
};

Handling Side Effects In Other Hooks

The other hooks presented in this chapter, starting with useQuery, don’t expose the dataProvider Promise. To allow for side effects with these hooks, they all accept an additional options argument. It’s an object with onSuccess and onFailure functions, that react-admin executes on success… or on failure.

So an <ApproveButton> written with useMutation instead of useDataProvider can specify side effects as follows:

import * as React from "react";
import { useMutation, useNotify, useRedirect, Button } from 'react-admin';

const ApproveButton = ({ record }) => {
    const notify = useNotify();
    const redirect = useRedirect();
    const [approve, { loading }] = useMutation(
        {
            type: 'update',
            resource: 'comments',
            payload: { id: record.id, data: { isApproved: true } },
        },
        {
            onSuccess: ({ data }) => {
                redirect('/comments');
                notify('Comment approved');
            },
            onFailure: (error) => notify(`Comment approval error: ${error.message}`, { type: 'warning' }),
        }
    );
    return <Button label="Approve" onClick={approve} disabled={loading} />;
};

Optimistic Rendering and Undo

In the previous example, after clicking on the “Approve” button, a loading spinner appears while the data provider is fetched. Then, users are redirected to the comments list. But in most cases, the server returns a success response, so the user waits for this response for nothing.

This is called pessimistic rendering, as all users are forced to wait because of the (usually rare) possibility of server failure.

An alternative mode for mutations is optimistic rendering. The idea is to handle the calls to the dataProvider on the client side first (i.e. updating entities in the Redux store), and re-render the screen immediately. The user sees the effect of their action with no delay. Then, react-admin applies the success side effects, and only after that, it triggers the call to the data provider. If the fetch ends with a success, react-admin does nothing more than a refresh to grab the latest data from the server. In most cases, the user sees no difference (the data in the Redux store and the data from the dataProvider are the same). If the fetch fails, react-admin shows an error notification, and forces a refresh, too.

A third mutation mode is called undoable. It’s like optimistic rendering, but with an added feature: after applying the changes and the side effects locally, react-admin waits for a few seconds before triggering the call to the dataProvider. During this delay, the end user sees an “undo” button that, when clicked, cancels the call to the dataProvider and refreshes the screen.

Here is a quick recap of the three mutation modes:

By default, react-admin uses the undoable mode for the Edit view. For the Create view, react-admin needs to wait for the response to know the id of the resource to redirect to, so the mutation mode is pessimistic.

You can benefit from optimistic and undoable modes when you call the useMutation hook, too. You just need to pass a mutationMode value in the options parameter:

import * as React from "react";
import { useMutation, useNotify, useRedirect, Button } from 'react-admin';

const ApproveButton = ({ record }) => {
    const notify = useNotify();
    const redirect = useRedirect();
    const [approve, { loading }] = useMutation(
        {
            type: 'update',
            resource: 'comments',
            payload: { id: record.id, data: { isApproved: true } },
        },
        {
+           mutationMode: 'undoable',
-           onSuccess: ({ data }) => {
+           onSuccess: () => {
                redirect('/comments');
-               notify('Comment approved');
+               notify('Comment approved', { undoable: true });
            },
            onFailure: (error) => notify(`Error: ${error.message}`, { type: 'warning' }),
        }
    );
    return <Button label="Approve" onClick={approve} disabled={loading} />;
};

As you can see in this example, you need to tweak the notification for undoable calls: passing true as fourth parameter of notify displays the ‘Undo’ button in the notification. Also, as side effects are executed immediately, they can’t rely on the response being passed to onSuccess.

You can pass the mutationMode option parameter to specialized hooks, too. They all accept an optional last argument with side effects.

import * as React from "react";
import { useUpdate, useNotify, useRedirect, Button } from 'react-admin';

const ApproveButton = ({ record }) => {
    const notify = useNotify();
    const redirect = useRedirect();
    const [approve, { loading }] = useUpdate(
        'comments',
        record.id,
        { isApproved: true },
        record,
        {
            mutationMode: 'undoable',
            onSuccess: () => {
                redirect('/comments');
                notify('Comment approved', { undoable: true });
            },
            onFailure: (error) => notify(`Error: ${error.message}`, { type: 'warning' }),
        }
    );
    return <Button label="Approve" onClick={approve} disabled={loading} />;
};

Customizing the Redux Action

The useDataProvider hook dispatches redux actions on load, on success, and on error. By default, these actions are called:

• CUSTOM_FETCH_LOAD
• CUSTOM_FETCH_SUCCESS
• CUSTOM_FETCH_FAILURE

React-admin doesn’t have any reducer watching these actions. You can write a custom reducer for these actions to store the return of the Data Provider in Redux. But the best way to do so is to set the hooks dispatch a custom action instead of CUSTOM_FETCH. Use the action option for that purpose:

import * as React from "react";
import { useUpdate, useNotify, useRedirect, Button } from 'react-admin';

const ApproveButton = ({ record }) => {
    const notify = useNotify();
    const redirect = useRedirect();
    const [approve, { loading }] = useUpdate(
        'comments',
        record.id,
        { isApproved: true },
        {
+           action: 'MY_CUSTOM_ACTION',
            mutationMode: 'undoable',
            onSuccess: ({ data }) => {
                redirect('/comments');
                notify('Comment approved', { undoable: true });
            },
            onFailure: (error) => notify(`Error: ${error.message}`, { type: 'warning' }),
        }
    );
    return <Button label="Approve" onClick={approve} disabled={loading} />;
};

Tip: When using the Data Provider hooks for regular pages (List, Edit, etc.), react-admin always specifies a custom action name, related to the component asking for the data. For instance, in the <List> page, the action is called CRUD_GET_LIST. So unless you call the Data Provider hooks yourself, no CUSTOM_FETCH action should be dispatched.

Legacy Components: <Query>, <Mutation>, and withDataProvider

Before React had hooks, react-admin used render props and higher order components to provide the same functionality. Legacy code will likely contain instances of <Query>, <Mutation>, and withDataProvider. Their syntax, which is identical to their hook counterpart, is illustrated below.

You can fetch and display a user profile using the <Query> component, which uses render props:

import * as React from "react";
import { Query, Loading, Error } from 'react-admin';

const UserProfile = ({ record }) => (
    <Query type='getOne' resource='users' payload={{ id: record.id }}>
        {({ data, loading, error }) => {
            if (loading) { return <Loading />; }
            if (error) { return <Error />; }
            return <div>User {data.username}</div>;
        }}
    </Query>
);

Or, query a user list on the dashboard with the same <Query> component:

import * as React from "react";
import { Query, Loading, Error } from 'react-admin';

const payload = {
   pagination: { page: 1, perPage: 10 },
   sort: { field: 'username', order: 'ASC' },
};

const UserList = () => (
    <Query type='getList' resource='users' payload={payload}>
        {({ data, total, loading, error }) => {
            if (loading) { return <Loading />; }
            if (error) { return <Error />; }
            return (
                <div>
                    <p>Total users: {total}</p>
                    <ul>
                        {data.map(user => <li key={user.username}>{user.username}</li>)}
                    </ul>
                </div>
            );
        }}
    </Query>
);

Just like useQuery, the <Query> component expects three parameters: type, resource, and payload. It fetches the data provider on mount, and passes the data to its child component once the response from the API arrives.

And if you need to chain API calls, don’t hesitate to nest <Query> components.

When calling the API to update (“mutate”) data, use the <Mutation> component instead. It passes a callback to trigger the API call to its child function.

Here is a version of the <ApproveButton> component demonstrating <Mutation>:

import * as React from "react";
import { Mutation, useNotify, useRedirect, Button } from 'react-admin';

const ApproveButton = ({ record }) => {
    const notify = useNotify();
    const redirect = useRedirect();
    const payload = { id: record.id, data: { ...record, is_approved: true } };
    const options = {
        mutationMode: 'undoable',
        onSuccess: ({ data }) => {
            notify('Comment approved', { undoable: true });
            redirect('/comments');
        },
        onFailure: (error) => notify(`Error: ${error.message}`, { type: 'warning' }),
    };
    return (
        <Mutation
            type='update'
            resource='comments'
            payload={payload}
            options={options}
        >
            {(approve, { loading }) => (
                <Button label='Approve' onClick={approve} disabled={loading} />
            )}
        </Mutation>
    );
};

export default ApproveButton;

And here is the <UserProfile> component using the withDataProvider HOC instead of the useDataProvider hook:

import { useState, useEffect } from 'react';
-import { useDataProvider } from 'react-admin';
+import { withDataProvider } from 'react-admin';

-const UserProfile = ({ userId }) => {
+const UserProfile = ({ userId, dataProvider }) => {
-   const dataProvider = useDataProvider();
    const [user, setUser] = useState();
    const [loading, setLoading] = useState(true);
    const [error, setError] = useState();
    useEffect(() => {
        dataProvider.getOne('users', { id: userId })
            .then(({ data }) => {
                setUser(data);
                setLoading(false);
            })
            .catch(error => {
                setError(error);
                setLoading(false);
            })
    }, []);

    if (loading) return <Loading />;
    if (error) return <Error />;
    if (!user) return null;

    return (
        <ul>
            <li>Name: {user.name}</li>
            <li>Email: {user.email}</li>
        </ul>
    )
};

-export default UserProfile;
+export default withDataProvider(UserProfile);

Note that these components are implemented in react-admin using the hooks described earlier. If you’re writing new components, prefer the hooks, which are faster, and do not pollute the component tree.

Querying The API With fetch

useQuery, useMutation and useDataProvider are “the react-admin way” to query the API, but nothing prevents you from using fetch if you want. For instance, when you don’t want to add some routing logic to the data provider for an RPC method on your API, that makes perfect sense.

There is no special react-admin sauce in that case. Here is an example implementation of calling fetch in a component:

// in src/comments/ApproveButton.js
import * as React from 'react';
import { useState } from 'react';
import { useDispatch } from 'react-redux';
import { useNotify, useRedirect, fetchStart, fetchEnd, Button } from 'react-admin';

const ApproveButton = ({ record }) => {
    const dispatch = useDispatch();
    const redirect = useRedirect();
    const notify = useNotify();
    const [loading, setLoading] = useState(false);
    const handleClick = () => {
        setLoading(true);
        dispatch(fetchStart()); // start the global loading indicator 
        const updatedRecord = { ...record, is_approved: true };
        fetch(`/comments/${record.id}`, { method: 'PUT', body: updatedRecord })
            .then(() => {
                notify('Comment approved');
                redirect('/comments');
            })
            .catch((e) => {
                notify('Error: comment not approved', { type: 'warning' })
            })
            .finally(() => {
                setLoading(false);
                dispatch(fetchEnd()); // stop the global loading indicator
            });
    };
    return <Button label="Approve" onClick={handleClick} disabled={loading} />;
};

export default ApproveButton;

TIP: APIs often require a bit of HTTP plumbing to deal with authentication, query parameters, encoding, headers, etc. It turns out you probably already have a function that maps from a REST request to an HTTP request: your Data Provider. So it’s often better to use useDataProvider instead of fetch.