ra-core-ee
Headless hooks and components for building enterprise-grade applications with React Admin.
Installation
npm install --save @react-admin/ra-core-ee
# or
yarn add @react-admin/ra-core-ee
Tip: ra-core-ee
is part of the React-Admin Enterprise Edition, and hosted in a private npm registry. You need to subscribe to one of the Enterprise Edition plans to access this package.
Authorization
getPermissionsFromRoles
This function returns an array of user permissions based on a role definition, a list of roles, and a list of user permissions. It merges the permissions defined in roleDefinitions
for the current user's roles (userRoles
) with the extra userPermissions
.
// static role definitions (usually in the app code)
const roleDefinitions = {
admin: [
{ action: '*', resource: '*' }
],
reader: [
{ action: ['list', 'show', 'export'], resource: '*' }
{ action: 'read', resource: 'posts.*' }
{ action: 'read', resource: 'comments.*' }
],
accounting: [
{ action: '*', resource: 'sales' },
],
};
const permissions = getPermissionsFromRoles({
roleDefinitions,
// roles of the current user (usually returned by the server upon login)
userRoles: ['reader'],
// extra permissions for the current user (usually returned by the server upon login)
userPermissions: [
{ action: 'list', resource: 'sales'},
],
});
// permissions = [
// { action: ['list', 'show', 'export'], resource: '*' },
// { action: 'read', resource: 'posts.*' },
// { action: 'read', resource: 'comments.*' },
// { action: 'list', resource: 'sales' },
// ];
This function takes an object as argument with the following fields:
roleDefinitions
: a dictionary containing the role definition for each roleuserRoles
(optional): an array of roles (admin, reader...) for the current useruserPermissions
(optional): an array of permissions for the current user
canAccessWithPermissions
canAccessWithPermissions
is a helper that facilitates the authProvider.canAccess()
method implementation:
import { canAccessWithPermissions } from '@react-admin/ra-core-ee';
const authProvider = {
// ...
canAccess: async ({ action, resource, record }) => {
const permissions = JSON.parse(localStorage.getItem('permissions'));
return canAccessWithPermissions({
permissions,
action,
resource,
record,
});
}
};
import { canAccessWithPermissions } from "@react-admin/ra-core-ee";
const authProvider = {
// ...
canAccess: async ({ action, resource, record }) => {
const permissions = JSON.parse(localStorage.getItem("permissions"));
return canAccessWithPermissions({
permissions,
action,
resource,
record,
});
},
};
canAccessWithPermissions
expects the permissions
to be a flat array of permissions. It is your responsibility to fetch these permissions (usually during login). If the permissions are spread into several role definitions, you can merge them into a single array using the getPermissionsFromRoles
function.
Realtime
Features
Publish/Subscribe
At its core, @react-admin/ra-core-ee
provides a pub/sub mechanism to send and receive real-time events. Events are sent to a topic, and all subscribers to this topic receive the event.
// on the publisher side
const [publish] = usePublish();
publish(topic, event);
// on the subscriber side
useSubscribe(topic, callback);
// on the publisher side
const [publish] = usePublish();
publish(topic, event);
// on the subscriber side
useSubscribe(topic, callback);
This package supports various realtime infrastructures (Mercure, API Platform, supabase, Socket.IO, Ably, and many more) thanks to the same adapter approach as for CRUD methods. In fact, the dataProvider
is used to send and receive events (see the Data Provider Requirements section for more information).
@react-admin/ra-core-ee
provides a set of high-level hooks to make it easy to work with real-time events:
Live Updates
Ra-realtime provides live updates via specialized hooks and components. This means that when a user edits a resource, the other users working on the same resource see the changes in real-time whether they are in a list, a show view, or an edit view.
For instance, include a <ListLiveUpdate>
within a <ListBase>
to have a list refreshing automatically when an element is added, updated, or deleted:
import { ListBase } from 'ra-core';
+import { ListLiveUpdate } from '@react-admin/ra-realtime';
const PostList = () => (
<ListBase>
...other children
+ <ListLiveUpdate />
</ListBase>
);
This feature leverages the following hooks:
-
useGetOneLive
` And the following components:
Locks
And last but not least, @react-admin/ra-core-ee
provides a lock mechanism to prevent two users from editing the same resource at the same time.
A user can lock a resource, either by voluntarily asking for a lock or by editing a resource. When a resource is locked, other users can't edit it. When the lock is released, other users can edit the resource again.
import { Form, useCreate, useGetIdentity, useRecordContext } from 'ra-core';
import { useGetLockLive } from '@react-admin/ra-core-ee';
import { TextInput, SelectInput } from '@components/admin/TextInput';
export const NewMessageForm = () => {
const [create, { isLoading: isCreating }] = useCreate();
const record = useRecordContext();
const { data: lock } = useGetLockLive('tickets', { id: record.id });
const { identity } = useGetIdentity();
const isFormDisabled = lock && lock.identity !== identity?.id;
const [doLock] = useLockOnCall({ resource: 'tickets' });
const handleSubmit = (values: any) => {
/* ... */
};
return (
<Form onSubmit={handleSubmit}>
<TextInput
source="message"
multiline
onFocus={() => {
doLock();
}}
disabled={isFormDisabled}
/>
<SelectInput
source="status"
choices={statusChoices}
disabled={isFormDisabled}
/>
<button type="submit" disabled={isCreating || isFormDisabled}>
Submit
</button>
</Form>
);
};
import { Form, useCreate, useGetIdentity, useRecordContext } from "ra-core";
import { useGetLockLive } from "@react-admin/ra-core-ee";
import { TextInput, SelectInput } from "@components/admin/TextInput";
export const NewMessageForm = () => {
const [create, { isLoading: isCreating }] = useCreate();
const record = useRecordContext();
const { data: lock } = useGetLockLive("tickets", { id: record.id });
const { identity } = useGetIdentity();
const isFormDisabled = lock && lock.identity !== identity?.id;
const [doLock] = useLockOnCall({ resource: "tickets" });
const handleSubmit = (values) => {
/* ... */
};
return (
<Form onSubmit={handleSubmit}>
<TextInput
source="message"
multiline
onFocus={() => {
doLock();
}}
disabled={isFormDisabled}
/>
<SelectInput source="status" choices={statusChoices} disabled={isFormDisabled} />
<button type="submit" disabled={isCreating || isFormDisabled}>
Submit
</button>
</Form>
);
};
This feature leverages the following hooks:
useLock
useUnlock
useGetLock
useGetLockLive
useGetLocks
useGetLocksLive
useLockOnCall
useLockOnMount
DataProvider Requirements
To enable real-time features, the dataProvider
must implement three new methods:
subscribe(topic, callback)
unsubscribe(topic, callback)
publish(topic, event)
(optional - publication is often done server-side)
These methods should return an empty Promise resolved when the action was acknowledged by the real-time bus.
In addition, to support the lock features, the dataProvider
must implement 4 more methods:
lock(resource, { id, identity, meta })
unlock(resource, { id, identity, meta })
getLock(resource, { id, meta })
getLocks(resource, { meta })
Supabase Adapter
The ra-realtime
package contains a function augmenting a regular (API-based) dataProvider
with real-time methods based on the capabilities of Supabase.
This adapter subscribes to Postgres Changes, and transforms the events into the format expected by ra-realtime
.
import { addRealTimeMethodsBasedOnSupabase, ListLiveUpdate } from '@react-admin/ra-core-ee';
import { supabaseDataProvider } from 'ra-supabase';
import { createClient } from '@supabase/supabase-js';
import { CoreAdmin, Resource, ListBase } from 'ra-core';
const supabaseClient = createClient(
process.env.SUPABASE_URL,
process.env.SUPABASE_ANON_KEY
);
const dataProvider = supabaseDataProvider({
instanceUrl: process.env.SUPABASE_URL,
apiKey: process.env.SUPABASE_ANON_KEY,
supabaseClient
});
const realTimeDataProvider = addRealTimeMethodsBasedOnSupabase({
dataProvider,
supabaseClient,
});
export const App = () => {
return (
<CoreAdmin dataProvider={realTimeDataProvider}>
<Resource name="sales" list={SaleList} />
</CoreAdmin>
);
};
const SaleList = () => (
<List>
{/* List view */}
<ListLiveUpdate />
</List>
);
import { addRealTimeMethodsBasedOnSupabase, ListLiveUpdate } from "@react-admin/ra-core-ee";
import { supabaseDataProvider } from "ra-supabase";
import { createClient } from "@supabase/supabase-js";
import { CoreAdmin, Resource } from "ra-core";
const supabaseClient = createClient(process.env.SUPABASE_URL, process.env.SUPABASE_ANON_KEY);
const dataProvider = supabaseDataProvider({
instanceUrl: process.env.SUPABASE_URL,
apiKey: process.env.SUPABASE_ANON_KEY,
supabaseClient,
});
const realTimeDataProvider = addRealTimeMethodsBasedOnSupabase({
dataProvider,
supabaseClient,
});
export const App = () => {
return (
<CoreAdmin dataProvider={realTimeDataProvider}>
<Resource name="sales" list={SaleList} />
</CoreAdmin>
);
};
const SaleList = () => (
<List>
{/* List view */}
<ListLiveUpdate />
</List>
);
Tip: Realtime features are not enabled in Supabase by default, you need to enable them. This can be done either from the Replication section of your Supabase Dashboard, or by running the following SQL query with the SQL Editor:
begin;
-- remove the supabase_realtime publication
drop
publication if exists supabase_realtime;
-- re-create the supabase_realtime publication with no tables
create publication supabase_realtime;
commit;
-- add a table to the publication
alter
publication supabase_realtime add table sales;
alter
publication supabase_realtime add table contacts;
alter
publication supabase_realtime add table contactNotes;
Have a look at the Supabase Replication Setup documentation section for more info.
addRealTimeMethodsBasedOnSupabase
accepts the following parameters:
Prop | Required | Type | Default | Description |
---|---|---|---|---|
dataProvider |
Required | DataProvider |
- | The base dataProvider to augment with realtime methods |
supabaseClient |
Required | SupabaseClient |
- | The Supabase JS Client |
Custom Tokens
You may choose to sign your own tokens to customize claims that can be checked in your RLS policies. In order to use these custom tokens with addRealTimeMethodsBasedOnSupabase
, you must pass apikey
in both Realtime's headers
and params
when creating the supabaseClient
.
Please follow the instructions from the Supabase documentation for more information about how to do so.
API-Platform Adapter
The ra-realtime
package contains a function augmenting a regular (API-based) dataProvider
with real-time methods based on the capabilities of API-Platform. Use it as follows:
import { ListBase } from 'ra-core';
import {
HydraAdmin,
ResourceGuesser,
FieldGuesser,
hydraDataProvider,
} from '@api-platform/admin';
import {
ListLiveUpdate,
addRealTimeMethodsBasedOnApiPlatform,
} from '@react-admin/ra-core-ee';
const dataProvider = hydraDataProvider({
entrypoint: 'https://localhost',
});
const realTimeDataProvider = addRealTimeMethodsBasedOnApiPlatform(
// The original dataProvider (should be a hydra data provider passed by API-Platform)
dataProvider,
// The API-Platform Mercure Hub URL
'https://localhost/.well-known/mercure',
// JWT token to authenticate against the API-Platform Mercure Hub
'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjdXJlIjp7InB1Ymxpc2giOlsiKiJdfX0.obDjwCgqtPuIvwBlTxUEmibbBf0zypKCNzNKP7Op2UM',
// The topic URL used by API-Platform (without a slash at the end)
'https://localhost'
);
const App = () => {
return (
<HydraAdmin
entrypoint="https://localhost"
dataProvider={realTimeDataProvider}
>
<ResourceGuesser name="greetings" list={GreetingsList} />
</HydraAdmin>
);
};
// Example for connecting a list of greetings
const GreetingsList = () => (
<ListBase>
{/* List view */}
</ListBase>
);
import { ListBase } from "ra-core";
import { HydraAdmin, ResourceGuesser, hydraDataProvider } from "@api-platform/admin";
import { addRealTimeMethodsBasedOnApiPlatform } from "@react-admin/ra-core-ee";
const dataProvider = hydraDataProvider({
entrypoint: "https://localhost",
});
const realTimeDataProvider = addRealTimeMethodsBasedOnApiPlatform(
// The original dataProvider (should be a hydra data provider passed by API-Platform)
dataProvider,
// The API-Platform Mercure Hub URL
"https://localhost/.well-known/mercure",
// JWT token to authenticate against the API-Platform Mercure Hub
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjdXJlIjp7InB1Ymxpc2giOlsiKiJdfX0.obDjwCgqtPuIvwBlTxUEmibbBf0zypKCNzNKP7Op2UM",
// The topic URL used by API-Platform (without a slash at the end)
"https://localhost"
);
const App = () => {
return (
<HydraAdmin entrypoint="https://localhost" dataProvider={realTimeDataProvider}>
<ResourceGuesser name="greetings" list={GreetingsList} />
</HydraAdmin>
);
};
// Example for connecting a list of greetings
const GreetingsList = () => <ListBase>{/* List view */}</ListBase>;
The addRealTimeMethodsBasedOnApiPlatform
function also accepts an optional 5th argument allowing to customize the transformTopicFromRaRealtime
function (responsible for transforming the topic
argument from the Admin
into a valid Mercure topic for Api Platform).
import { hydraDataProvider } from '@api-platform/admin';
import { addRealTimeMethodsBasedOnApiPlatform } from '@react-admin/ra-realtime';
const dataProvider = hydraDataProvider({
entrypoint: 'https://localhost',
});
function myTransformTopicFromRaRealtime(topic: string): string {
const [_basename, _resourcePrefix, resource, ...id] = topic.split('/');
if (!id || id.length === 0) {
return `/${resource}/{id}`;
}
const originId = id[2];
return `/${resource}/${originId}`;
}
const realTimeDataProvider = addRealTimeMethodsBasedOnApiPlatform(
dataProvider,
'https://localhost/.well-known/mercure',
'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjdXJlIjp7InB1Ymxpc2giOlsiKiJdfX0.obDjwCgqtPuIvwBlTxUEmibbBf0zypKCNzNKP7Op2UM',
'https://localhost',
// Pass the custom transformTopicFromRaRealtime function here
myTransformTopicFromRaRealtime
);
import { hydraDataProvider } from "@api-platform/admin";
import { addRealTimeMethodsBasedOnApiPlatform } from "@react-admin/ra-realtime";
const dataProvider = hydraDataProvider({
entrypoint: "https://localhost",
});
function myTransformTopicFromRaRealtime(topic) {
const [_basename, _resourcePrefix, resource, ...id] = topic.split("/");
if (!id || id.length === 0) {
return `/${resource}/{id}`;
}
const originId = id[2];
return `/${resource}/${originId}`;
}
const realTimeDataProvider = addRealTimeMethodsBasedOnApiPlatform(
dataProvider,
"https://localhost/.well-known/mercure",
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjdXJlIjp7InB1Ymxpc2giOlsiKiJdfX0.obDjwCgqtPuIvwBlTxUEmibbBf0zypKCNzNKP7Op2UM",
"https://localhost",
// Pass the custom transformTopicFromRaRealtime function here
myTransformTopicFromRaRealtime
);
Mercure Adapter
The ra-realtime
package contains a function augmenting a regular (API-based) dataProvider
with real-time methods based on a Mercure hub. Use it as follows:
import { addRealTimeMethodsBasedOnMercure } from '@react-admin/ra-core-ee';
import { CoreAdmin } from 'ra-core';
const realTimeDataProvider = addRealTimeMethodsBasedOnMercure(
// original dataProvider
dataProvider,
// Mercure hub URL
'http://path.to.my.api/.well-known/mercure',
// JWT token to authenticate against the Mercure Hub
'eyJhbGciOiJIUzI1NiJ9.eyJtZXJjdXJlIjp7InB1Ymxpc2giOlsiKiJdLCJzdWJzY3JpYmUiOlsiKiJdfX0.SWKHNF9wneXTSjBg81YN5iH8Xb2iTf_JwhfUY5Iyhsw'
);
const App = () => (
<CoreAdmin dataProvider={realTimeDataProvider}>{/* ... */}</CoreAdmin>
);
import { addRealTimeMethodsBasedOnMercure } from "@react-admin/ra-core-ee";
import { CoreAdmin } from "ra-core";
const realTimeDataProvider = addRealTimeMethodsBasedOnMercure(
// original dataProvider
dataProvider,
// Mercure hub URL
"http://path.to.my.api/.well-known/mercure",
// JWT token to authenticate against the Mercure Hub
"eyJhbGciOiJIUzI1NiJ9.eyJtZXJjdXJlIjp7InB1Ymxpc2giOlsiKiJdLCJzdWJzY3JpYmUiOlsiKiJdfX0.SWKHNF9wneXTSjBg81YN5iH8Xb2iTf_JwhfUY5Iyhsw"
);
const App = () => <CoreAdmin dataProvider={realTimeDataProvider}>{/* ... */}</CoreAdmin>;
Writing a Custom Adapter
If you're using another transport for real-time messages (WebSockets, long polling, GraphQL subscriptions, etc.), you'll have to implement subscribe
, unsubscribe
, and publish
yourself in your dataProvider
. As an example, here is an implementation using a local variable, that ra-realtime
uses in tests:
let subscriptions = [];
const dataProvider = {
// regular dataProvider methods like getList, getOne, etc,
// ...
subscribe: async (topic, subscriptionCallback) => {
subscriptions.push({ topic, subscriptionCallback });
return Promise.resolve({ data: null });
},
unsubscribe: async (topic, subscriptionCallback) => {
subscriptions = subscriptions.filter(
subscription =>
subscription.topic !== topic ||
subscription.subscriptionCallback !== subscriptionCallback
);
return Promise.resolve({ data: null });
},
publish: (topic, event) => {
if (!topic) {
return Promise.reject(new Error('missing topic'));
}
if (!event.type) {
return Promise.reject(new Error('missing event type'));
}
subscriptions.map(
subscription =>
topic === subscription.topic &&
subscription.subscriptionCallback(event)
);
return Promise.resolve({ data: null });
},
};
let subscriptions = [];
const dataProvider = {
// regular dataProvider methods like getList, getOne, etc,
// ...
subscribe: async (topic, subscriptionCallback) => {
subscriptions.push({ topic, subscriptionCallback });
return Promise.resolve({ data: null });
},
unsubscribe: async (topic, subscriptionCallback) => {
subscriptions = subscriptions.filter(
(subscription) => subscription.topic !== topic || subscription.subscriptionCallback !== subscriptionCallback
);
return Promise.resolve({ data: null });
},
publish: (topic, event) => {
if (!topic) {
return Promise.reject(new Error("missing topic"));
}
if (!event.type) {
return Promise.reject(new Error("missing event type"));
}
subscriptions.map((subscription) => topic === subscription.topic && subscription.subscriptionCallback(event));
return Promise.resolve({ data: null });
},
};
You can check the behavior of the real-time components by using the default console logging provided in addRealTimeMethodsInLocalBrowser
.
Topic And Event Format
You've noticed that all the dataProvider
real-time methods expect a topic
as the first argument. A topic
is just a string, identifying a particular real-time channel. Topics can be used e.g. to dispatch messages to different rooms in a chat application or to identify changes related to a particular record.
Most ra-realtime
components deal with CRUD logic, so ra-realtime
subscribes to special topics named resource/[name]
and resource/[name]/[id]
. For your own events, use any topic
you want.
The event
is the name of the message sent from publishers to subscribers. An event
should be a JavaScript object with a type
and a payload
field.
Here is an example event:
{
type: 'created',
payload: 'New message',
}
For CRUD operations, ra-realtime
expects events to use the types 'created', 'updated', and 'deleted'.
CRUD Events
Ra-realtime has deep integration with react-admin, where most of the logic concerns Creation, Update or Deletion (CRUD) of records. To enable this integration, your real-time backend should publish the following events:
- when a new record is created:
{
topic: `resource/${resource}`,
event: {
type: 'created',
payload: { ids: [id]},
},
}
- when a record is updated:
{
topic: `resource/${resource}/id`,
event: {
type: 'updated',
payload: { ids: [id]},
},
}
{
topic: `resource/${resource}`,
event: {
type: 'updated',
payload: { ids: [id]},
},
}
- when a record is deleted:
{
topic: `resource/${resource}/id`,
event: {
type: 'deleted',
payload: { ids: [id]},
},
}
{
topic: `resource/${resource}`,
event: {
type: 'deleted',
payload: { ids: [id]},
},
}
Lock Format
A lock
stores the record that is locked, the identity of the locker, and the time at which the lock was acquired. It is used to prevent concurrent editing of the same record. A typical lock looks like this:
{
resource: 'posts',
recordId: 123,
identity: 'julien',
createdAt: '2023-01-02T21:36:35.133Z',
}
The dataProvider.getLock()
and dataProvider.getLocks()
methods should return these locks.
As for the mutation methods (dataProvider.lock()
, dataProvider.unlock()
), they expect the following parameters:
resource
: the resource name (e.g.'posts'
)params
: an object containing the followingid
: the record id (e.g.123
)identity
: an identifier (string or number) corresponding to the identity of the locker (e.g.'julien'
). This could be an authentication token for instance.meta
: an object that will be forwarded to the dataProvider (optional)
Locks Based On A Lock Resource
The ra-realtime
package offers a function augmenting a regular (API-based) dataProvider
with locks methods based on a locks
resource.
It will translate a dataProvider.getLocks()
call to a dataProvider.getList('locks')
call, and a dataProvider.lock()
call to a dataProvider.create('locks')
call.
The lock
resource should contain the following fields:
{
"id": 123,
"identity": "Toad",
"resource": "people",
"recordId": 18,
"createdAt": "2020-09-29 10:20"
}
Please note that the identity
and the createdAt
formats depend on your API.
Here is how to use it in your react-admin application:
import { CoreAdmin } from 'ra-core';
import { addLocksMethodsBasedOnALockResource } from '@react-admin/ra-core-ee';
const dataProviderWithLocks = addLocksMethodsBasedOnALockResource(
dataProvider // original dataProvider
);
const App = () => (
<CoreAdmin dataProvider={dataProviderWithLocks}>{/* ... */}</CoreAdmin>
);
import { CoreAdmin } from "ra-core";
import { addLocksMethodsBasedOnALockResource } from "@react-admin/ra-core-ee";
const dataProviderWithLocks = addLocksMethodsBasedOnALockResource(
dataProvider // original dataProvider
);
const App = () => <CoreAdmin dataProvider={dataProviderWithLocks}>{/* ... */}</CoreAdmin>;
dataProvider
Methods Directly
Calling the Once you've set a real-time dataProvider
, you can call the real-time methods in your React components via the useDataProvider
hook.
For instance, here is a component displaying messages posted to the 'messages' topic in real time:
import React, { useState } from 'react';
import { useDataProvider, useNotify } from 'ra-core';
const MessageList = () => {
const notify = useNotify();
const [messages, setMessages] = useState([]);
const dataProvider = useDataProvider();
useEffect(() => {
const callback = event => {
// event is like
// {
// topic: 'messages',
// type: 'created',
// payload: 'New message',
// }
setMessages(messages => [...messages, event.payload]);
notify('New message');
};
// subscribe to the 'messages' topic on mount
dataProvider.subscribe('messages', callback);
// unsubscribe on unmount
return () => dataProvider.unsubscribe('messages', callback);
}, [setMessages, notify, dataProvider]);
return (
<ul>
{messages.map((message, index) => (
<li key={index}>{message}</li>
))}
</ul>
);
};
import React, { useState } from "react";
import { useDataProvider, useNotify } from "ra-core";
const MessageList = () => {
const notify = useNotify();
const [messages, setMessages] = useState([]);
const dataProvider = useDataProvider();
useEffect(() => {
const callback = (event) => {
// event is like
// {
// topic: 'messages',
// type: 'created',
// payload: 'New message',
// }
setMessages((messages) => [...messages, event.payload]);
notify("New message");
};
// subscribe to the 'messages' topic on mount
dataProvider.subscribe("messages", callback);
// unsubscribe on unmount
return () => dataProvider.unsubscribe("messages", callback);
}, [setMessages, notify, dataProvider]);
return (
<ul>
{messages.map((message, index) => (
<li key={index}>{message}</li>
))}
</ul>
);
};
And here is a button for publishing an event to the messages
topic. All the subscribers to this topic will execute their callback:
import React from 'react';
import { useDataProvider, useNotify } from 'ra-core';
const SendMessageButton = () => {
const dataProvider = useDataProvider();
const notify = useNotify();
const handleClick = () => {
dataProvider
.publish('messages', { type: 'created', payload: 'New message' })
.then(() => notify('Message sent'));
};
return <button onClick={handleClick}>Send new message</button>;
};
import React from "react";
import { useDataProvider, useNotify } from "ra-core";
const SendMessageButton = () => {
const dataProvider = useDataProvider();
const notify = useNotify();
const handleClick = () => {
dataProvider
.publish("messages", { type: "created", payload: "New message" })
.then(() => notify("Message sent"));
};
return <button onClick={handleClick}>Send new message</button>;
};
Tip: You should not need to call publish()
directly very often. Most real-time backends publish events in reaction to a change in the data. So the previous example is fictive. In reality, a typical <SendMessageButton>
would simply call dataProvider.create('messages')
, and the API would create the new message AND publish the 'created' event to the real-time bus.
Hooks
usePublish
Get a callback to publish an event on a topic. The callback returns a promise that resolves when the event is published.
usePublish
calls dataProvider.publish()
to publish the event. It leverages react-query's useMutation
hook to provide a callback.
Note: Events should generally be published by the server, in reaction to an action by an end user. They should seldom be published directly by the client. This hook is provided mostly for testing purposes, but you may use it in your own custom components if you know what you're doing.
Usage
usePublish
returns a callback with the following signature:
const publish = usePublish();
publish(topic, event, options);
const publish = usePublish();
publish(topic, event, options);
For instance, in a chat application, when a user is typing a message, the following component publishes a typing
event to the chat/[channel]
topic:
import { useInput, useGetIdentity } from 'ra-core';
import { usePublish } from '@react-admin/ra-core-ee';
const MessageInput = ({ channel }) => {
const [publish, { isLoading }] = usePublish();
const { id, field, fieldState } = useInput({ source: 'message' });
const { identity } = useGetIdentity();
const handleUserInput = event => {
publish(`chat/${channel}`, {
type: 'typing',
payload: { user: identity },
});
};
return (
<label htmlFor={id}>
Type your message
<input id={id} {...field} onInput={handleUserInput} />
</label>
);
};
import { useInput, useGetIdentity } from "ra-core";
import { usePublish } from "@react-admin/ra-core-ee";
const MessageInput = ({ channel }) => {
const [publish, { isLoading }] = usePublish();
const { id, field, fieldState } = useInput({ source: "message" });
const { identity } = useGetIdentity();
const handleUserInput = (event) => {
publish(`chat/${channel}`, {
type: "typing",
payload: { user: identity },
});
};
return (
<label htmlFor={id}>
Type your message
<input id={id} {...field} onInput={handleUserInput} />
</label>
);
};
The event format is up to you. It should at least contain a type
property and may contain a payload
property. The payload
property can contain any data you want to send to the subscribers.
Some hooks and components in this package are specialized to handle "CRUD" events, which are events with a type
property set to created
, updated
or deleted
. For instance:
{
topic: `resource/${resource}/id`,
event: {
type: 'deleted',
payload: { ids: [id]},
},
}
See the CRUD events section for more details.
Return Value
usePublish
returns an array with the following values:
publish
: The callback to publish an event to a topic.state
: The state of the mutation (see react-query documentation). Notable properties:isLoading
: Whether the mutation is loading.error
: The error if the mutation failed.data
: The published event if the mutation succeeded.
const [publish, { isLoading, error, data }] = usePublish();
const [publish, { isLoading, error, data }] = usePublish();
Callback Parameters
The publish
callback accepts the following parameters:
topic
: The topic to publish the event on.event
: The event to publish. It must contain atype
property.options
:useMutation
options (see react-query documentation). Notable properties:onSuccess
: A callback to call when the event is published. It receives the published event as its first argument.onError
: A callback to call when the event could not be published. It receives the error as its first argument.retry
: Whether to retry on failure. Defaults to0
.
const [publish] = usePublish();
publish(
'chat/general',
{
type: 'message',
payload: { user: 'John', message: 'Hello!' },
},
{
onSuccess: event => console.log('Event published', event),
onError: error => console.log('Could not publish event', error),
retry: 3,
}
);
const [publish] = usePublish();
publish(
"chat/general",
{
type: "message",
payload: { user: "John", message: "Hello!" },
},
{
onSuccess: (event) => console.log("Event published", event),
onError: (error) => console.log("Could not publish event", error),
retry: 3,
}
);
useSubscribe
Subscribe to the events from a topic on mount (and unsubscribe on unmount).
Usage
The following component subscribes to the messages/{channelName}
topic and displays a badge with the number of unread messages:
import { useState, useCallback } from 'react';
import { useSubscribe } from '@react-admin/ra-core-ee';
const ChannelName = ({ name }) => {
const [nbMessages, setNbMessages] = useState(0);
const callback = useCallback(
event => {
if (event.type === 'created') {
setNbMessages(count => count + 1);
}
},
[setNbMessages]
);
useSubscribe(`messages/${name}`, callback);
return nbMessages > 0 ? (
<p>#{name} ({nbMessages} new messages)</p>
) : (
<p>#{name}</p>
);
};
import { useState, useCallback } from "react";
import { useSubscribe } from "@react-admin/ra-core-ee";
const ChannelName = ({ name }) => {
const [nbMessages, setNbMessages] = useState(0);
const callback = useCallback(
(event) => {
if (event.type === "created") {
setNbMessages((count) => count + 1);
}
},
[setNbMessages]
);
useSubscribe(`messages/${name}`, callback);
return nbMessages > 0 ? (
<p>
#{name} ({nbMessages} new messages)
</p>
) : (
<p>#{name}</p>
);
};
Parameters
Prop | Required | Type | Default | Description |
---|---|---|---|---|
topic |
Optional | string |
- | The topic to subscribe to. When empty, no subscription is created. |
callback |
Optional | function |
- | The callback to execute when an event is received. |
options |
Optional | object |
- | Options to modify the subscription / unsubscription behavior. |
callback
This function will be called with the event as its first argument, so you can use it to update the UI.
useSubscribe(`messages/${name}`, event => {
if (event.type === 'created') {
setNbMessages(count => count + 1);
}
});
useSubscribe(`messages/${name}`, (event) => {
if (event.type === "created") {
setNbMessages((count) => count + 1);
}
});
Tip: Memoize the callback using useCallback
to avoid unnecessary subscriptions/unsubscriptions.
const callback = useCallback(
event => {
if (event.type === 'created') {
setNbMessages(count => count + 1);
}
},
[setNbMessages]
);
useSubscribe(`messages/${name}`, callback);
const callback = useCallback(
(event) => {
if (event.type === "created") {
setNbMessages((count) => count + 1);
}
},
[setNbMessages]
);
useSubscribe(`messages/${name}`, callback);
The callback function receives an unsubscribe
callback as its second argument. You can call it to unsubscribe from the topic after receiving a specific event.
import { useState, useCallback } from 'react';
import { useSubscribe } from '@react-admin/ra-core-ee';
const JobProgress = ({ jobId }) => {
const [progress, setProgress] = useState(0);
const callback = useCallback(
(event, unsubscribe) => {
if (event.type === 'progress') {
setProgress(event.payload.progress);
}
if (event.type === 'completed') {
unsubscribe();
}
},
[setColor]
);
useSubscribe(`jobs/${jobId}`, callback);
return (
<div>{progress}%</div>
);
};
import { useState, useCallback } from "react";
import { useSubscribe } from "@react-admin/ra-core-ee";
const JobProgress = ({ jobId }) => {
const [progress, setProgress] = useState(0);
const callback = useCallback(
(event, unsubscribe) => {
if (event.type === "progress") {
setProgress(event.payload.progress);
}
if (event.type === "completed") {
unsubscribe();
}
},
[setColor]
);
useSubscribe(`jobs/${jobId}`, callback);
return <div>{progress}%</div>;
};
options
The options
object can contain the following properties:
enabled
: Whether to subscribe or not. Defaults totrue
once
: Whether to unsubscribe after the first event. Defaults tofalse
.unsubscribeOnUnmount
: Whether to unsubscribe on unmount. Defaults totrue
.
You can use the once
option to subscribe to a topic only once, and then unsubscribe.
For instance, the following component subscribes to the office/restart
topic and changes the message when the office is open, then unsubscribes from the topic:
import { useState } from 'react';
import { useSubscribe } from '@react-admin/ra-core-ee';
const OfficeClosed = () => {
const [state, setState] = useState('closed');
useSubscribe('office/restart', () => setState('open'), { once: true });
return (
<div>
{state === 'closed'
? 'Sorry, the office is closed for maintenance.'
: 'Welcome! The office is open.'}
</div>
);
};
import { useState } from "react";
import { useSubscribe } from "@react-admin/ra-core-ee";
const OfficeClosed = () => {
const [state, setState] = useState("closed");
useSubscribe("office/restart", () => setState("open"), { once: true });
return (
<div>
{state === "closed" ? "Sorry, the office is closed for maintenance." : "Welcome! The office is open."}
</div>
);
};
topic
The first argument of useSubscribe
is the topic to subscribe to. It can be an arbitrary string.
useSubscribe('messages', event => {
// ...
});
useSubscribe("messages", (event) => {
// ...
});
If you want to subscribe to CRUD events, instead of writing the topic manually like resource/[resource]
, you can use the useSubscribeToRecord
or useSubscribeToRecordList
hooks.
useSubscribeCallback
Get a callback to subscribe to events on a topic and optionally unsubscribe on unmount.
This is useful to start a subscription from an event handler, like a button click.
Usage
The following component subscribes to the backgroundJobs/recompute
topic on click, and displays the progress of the background job:
import { useState, useCallback } from 'react';
import { useDataProvider } from 'ra-core';
import { useSubscribeCallback } from '@react-admin/ra-core-ee';
const LaunchBackgroundJob = () => {
const dataProvider = useDataProvider();
const [progress, setProgress] = useState(0);
const callback = useCallback(
(event, unsubscribe) => {
setProgress(event.payload?.progress || 0);
if (event.payload?.progress === 100) {
unsubscribe();
}
},
[setProgress]
);
const subscribe = useSubscribeCallback(
'backgroundJobs/recompute',
callback
);
return (
<div>
<button
onClick={() => {
subscribe();
dataProvider.recompute();
}}
>
{progress === 0 ? 'Launch recompute' : `Recompute in progress (${progress}%)`}
</button>
</div>
);
};
import { useState, useCallback } from "react";
import { useDataProvider } from "ra-core";
import { useSubscribeCallback } from "@react-admin/ra-core-ee";
const LaunchBackgroundJob = () => {
const dataProvider = useDataProvider();
const [progress, setProgress] = useState(0);
const callback = useCallback(
(event, unsubscribe) => {
setProgress(event.payload?.progress || 0);
if (event.payload?.progress === 100) {
unsubscribe();
}
},
[setProgress]
);
const subscribe = useSubscribeCallback("backgroundJobs/recompute", callback);
return (
<div>
<button
onClick={() => {
subscribe();
dataProvider.recompute();
}}
>
{progress === 0 ? "Launch recompute" : `Recompute in progress (${progress}%)`}
</button>
</div>
);
};
Parameters
Prop | Required | Type | Default | Description |
---|---|---|---|---|
topic |
Optional | string |
- | The topic to subscribe to. When empty, no subscription is created. |
callback |
Optional | function |
- | The callback to execute when an event is received. |
options |
Optional | object |
- | Options to modify the subscription / unsubscription behavior. |
callback
Whenever an event is published on the topic
passed as the first argument, the function passed as the second argument will be called with the event as a parameter.
const subscribe = useSubscribeCallback('backgroundJobs/recompute', event => {
if (event.type === 'progress') {
setProgress(event.payload.progress);
}
});
// later
subscribe();
const subscribe = useSubscribeCallback("backgroundJobs/recompute", (event) => {
if (event.type === "progress") {
setProgress(event.payload.progress);
}
});
// later
subscribe();
Tip: Memoize the callback using useCallback
to avoid unnecessary subscriptions/unsubscriptions.
const callback = useCallback(
event => {
if (event.type === 'progress') {
setProgress(event.payload.progress);
}
},
[setProgress]
);
const callback = useCallback(
(event) => {
if (event.type === "progress") {
setProgress(event.payload.progress);
}
},
[setProgress]
);
The callback function receives an unsubscribe
callback as its second argument. You can call it to unsubscribe from the topic after receiving a specific event.
const subscribe = useSubscribeCallback(
'backgroundJobs/recompute',
(event, unsubscribe) => {
if (event.type === 'completed') {
setProgress(100);
unsubscribe();
}
}
);
const subscribe = useSubscribeCallback("backgroundJobs/recompute", (event, unsubscribe) => {
if (event.type === "completed") {
setProgress(100);
unsubscribe();
}
});
options
The options
object can contain the following properties:
enabled
: Whether to subscribe or not. Defaults totrue
once
: Whether to unsubscribe after the first event. Defaults tofalse
.unsubscribeOnUnmount
: Whether to unsubscribe on unmount. Defaults totrue
.
You can use the once
option to subscribe to a topic only once, and then unsubscribe.
For instance, the following component subscribes to the backgroundJobs/recompute
topic on click, displays a notification when the background job is complete, then unsubscribes:
import { useDataProvider, useNotify } from 'ra-core';
import { useSubscribeCallback } from '@react-admin/ra-core-ee';
const LaunchBackgroundJob = () => {
const dataProvider = useDataProvider();
const notify = useNotify();
const subscribe = useSubscribeCallback(
'backgroundJobs/recompute',
event =>
notify('Recompute complete: %{summary}', {
type: 'success',
messageArgs: {
summary: event.payload?.summary,
},
}),
{
unsubscribeOnUnmount: false, // show the notification even if the user navigates away
once: true, // unsubscribe after the first event
}
);
return (
<button
onClick={() => {
subscribe();
dataProvider.recompute();
}}
>
Launch background job
</button>
);
};
You can use the unsubscribeOnUnmount
option to keep the subscription alive after the component unmounts.
This can be useful when you want the subscription to persist across multiple pages.
const subscribe = useSubscribeCallback(
'backgroundJobs/recompute',
event => setProgress(event.payload?.progress || 0),
{
unsubscribeOnUnmount: false, // don't unsubscribe on unmount
}
);
const subscribe = useSubscribeCallback(
"backgroundJobs/recompute",
(event) => setProgress(event.payload?.progress || 0),
{
unsubscribeOnUnmount: false, // don't unsubscribe on unmount
}
);
topic
The first argument of useSubscribeCallback
is the topic to subscribe to. It can be an arbitrary string.
const subscribe = useSubscribeCallback('backgroundJobs/recompute', event => {
// ...
});
// later
subscribe();
const subscribe = useSubscribeCallback("backgroundJobs/recompute", (event) => {
// ...
});
// later
subscribe();
useSubscribeToRecord
This specialized version of useSubscribe
subscribes to events concerning a single record.
Usage
The hook expects a callback function as its only argument, as it guesses the record and resource from the current context. The callback will be executed whenever an event is published on the resource/[resource]/[recordId]
topic.
For instance, the following component displays a message when the record is updated by someone else:
const WarnWhenUpdatedBySomeoneElse = () => {
const [open, setOpen] = useState(false);
const [author, setAuthor] = useState<string | null>(null);
const handleClose = () => {
setOpen(false);
};
const { refetch } = useEditContext();
const refresh = () => {
refetch();
handleClose();
};
const {
formState: { isDirty },
} = useFormContext();
useSubscribeToRecord((event: Event) => {
if (event.type === 'edited') {
if (isDirty) {
setOpen(true);
setAuthor(event.payload.user);
} else {
refetch();
}
}
});
return open ? (
<div className="flex flex-col gap-4">
<p>
Post Updated by {author}
</p>
<p>
Your changes and their changes may conflict. What do you
want to do?
</p>
<div className="flex gap-4">
<button onClick={handleClose}>Keep my changes</button>
<button onClick={refresh}>
Get their changes (and lose mine)
</button>
</div>
</div>
) : null;
};
const PostEdit = () => (
<EditBase>
<Form>
{/* Inputs... */}
<WarnWhenUpdatedBySomeoneElse />
</Form>
</EditBase>
);
const WarnWhenUpdatedBySomeoneElse = () => {
const [open, setOpen] = useState(false);
const [author, setAuthor] = useState(null);
const handleClose = () => {
setOpen(false);
};
const { refetch } = useEditContext();
const refresh = () => {
refetch();
handleClose();
};
const {
formState: { isDirty },
} = useFormContext();
useSubscribeToRecord((event) => {
if (event.type === "edited") {
if (isDirty) {
setOpen(true);
setAuthor(event.payload.user);
} else {
refetch();
}
}
});
return open ? (
<div className="flex flex-col gap-4">
<p>Post Updated by {author}</p>
<p>Your changes and their changes may conflict. What do you want to do?</p>
<div className="flex gap-4">
<button onClick={handleClose}>Keep my changes</button>
<button onClick={refresh}>Get their changes (and lose mine)</button>
</div>
</div>
) : null;
};
const PostEdit = () => (
<EditBase>
<Form>
{/* Inputs... */}
<WarnWhenUpdatedBySomeoneElse />
</Form>
</EditBase>
);
useSubscribeToRecord
reads the current resource and record from the ResourceContext
and RecordContext
respectively. In the example above, the notification is displayed when the app receives an event on the resource/books/123
topic.
Just like useSubscribe
, useSubscribeToRecord
unsubscribes from the topic when the component unmounts.
Tip: In the example above, <Show>
creates the RecordContext
- that's why the useSubscribeToRecord
hook is used in its child component instead of in the <BookShow>
component.
You can provide the resource and record id explicitly if you are not in such contexts:
useSubscribeToRecord(
event => {
/* ... */
},
'posts',
123
);
useSubscribeToRecord(
(event) => {
/* ... */
},
"posts",
123
);
Tip: If your reason to subscribe to events on a record is to keep the record up to date, you should use the useGetOneLive
hook instead.
Parameters
Prop | Required | Type | Default | Description |
---|---|---|---|---|
callback |
Required | function |
- | The callback to execute when an event is received. |
resource |
Optional | string |
- | The resource to subscribe to. Defaults to the resource in the ResourceContext . |
recordId |
Optional | string |
- | The record id to subscribe to. Defaults to the id of the record in the RecordContext . |
options |
Optional | object |
- | The subscription options. |
callback
Whenever an event is published on the resource/[resource]/[recordId]
topic, the function passed as the first argument will be called with the event as a parameter.
const [open, setOpen] = useState(false);
const [author, setAuthor] = useState<string | null>(null);
const { refetch } = useEditContext();
const {
formState: { isDirty },
} = useFormContext();
useSubscribeToRecord((event: Event) => {
if (event.type === 'edited') {
if (isDirty) {
setOpen(true);
setAuthor(event.payload.user);
} else {
refetch();
}
}
});
const [open, setOpen] = useState(false);
const [author, setAuthor] = useState(null);
const { refetch } = useEditContext();
const {
formState: { isDirty },
} = useFormContext();
useSubscribeToRecord((event) => {
if (event.type === "edited") {
if (isDirty) {
setOpen(true);
setAuthor(event.payload.user);
} else {
refetch();
}
}
});
Tip: Memoize the callback using useCallback
to avoid unnecessary subscriptions/unsubscriptions.
const [open, setOpen] = useState(false);
const [author, setAuthor] = useState<string | null>(null);
const { refetch } = useEditContext();
const {
formState: { isDirty },
} = useFormContext();
const handleEvent = useCallback(
(event: Event) => {
if (event.type === 'edited') {
if (isDirty) {
setOpen(true);
setAuthor(event.payload.user);
} else {
refetch();
}
}
},
[isDirty, refetch, setOpen, setAuthor]
);
useSubscribeToRecord(handleEvent);
const [open, setOpen] = useState(false);
const [author, setAuthor] = useState(null);
const { refetch } = useEditContext();
const {
formState: { isDirty },
} = useFormContext();
const handleEvent = useCallback(
(event) => {
if (event.type === "edited") {
if (isDirty) {
setOpen(true);
setAuthor(event.payload.user);
} else {
refetch();
}
}
},
[isDirty, refetch, setOpen, setAuthor]
);
useSubscribeToRecord(handleEvent);
Just like for useSubscribe
, the callback function receives an unsubscribe
callback as its second argument. You can call it to unsubscribe from the topic after receiving a specific event.
useSubscribeToRecord((event: Event, unsubscribe) => {
if (event.type === 'deleted') {
// do something
unsubscribe();
}
if (event.type === 'edited') {
if (isDirty) {
setOpen(true);
setAuthor(event.payload.user);
} else {
refetch();
}
}
});
useSubscribeToRecord((event, unsubscribe) => {
if (event.type === "deleted") {
// do something
unsubscribe();
}
if (event.type === "edited") {
if (isDirty) {
setOpen(true);
setAuthor(event.payload.user);
} else {
refetch();
}
}
});
options
The options
object can contain the following properties:
enabled
: Whether to subscribe or not. Defaults totrue
once
: Whether to unsubscribe after the first event. Defaults tofalse
.unsubscribeOnUnmount
: Whether to unsubscribe on unmount. Defaults totrue
.
See useSubscribe
for more details.
recordId
The record id to subscribe to. By default, useSubscribeToRecord
builds the topic it subscribes to using the id of the record in the RecordContext
. But you can override this behavior by passing a record id as the third argument.
// will subscribe to the 'resource/posts/123' topic
useSubscribeToRecord(
event => {
/* ... */
},
'posts',
123
);
// will subscribe to the 'resource/posts/123' topic
useSubscribeToRecord(
(event) => {
/* ... */
},
"posts",
123
);
Note that if you pass a null record id, the hook will not subscribe to any topic.
resource
The resource to subscribe to. By default, useSubscribeToRecord
builds the topic it subscribes to using the resource in the ResourceContext
. But you can override this behavior by passing a resource name as the second argument.
// will subscribe to the 'resource/posts/123' topic
useSubscribeToRecord(
event => {
/* ... */
},
'posts',
123
);
// will subscribe to the 'resource/posts/123' topic
useSubscribeToRecord(
(event) => {
/* ... */
},
"posts",
123
);
Note that if you pass an empty string as the resource name, the hook will not subscribe to any topic.
useSubscribeToRecordList
This specialized version of useSubscribe
subscribes to events concerning a list of records.
Usage
useSubscribeToRecordList
expects a callback function as its first argument. It will be executed whenever an event is published on the resource/[resource]
topic.
For instance, the following component displays notifications when a record is created, updated, or deleted by someone else:
import React from 'react';
import { useNotify, useListContext } from 'ra-core';
import { useSubscribeToRecordList } from '@react-admin/ra-core-ee';
const ListWatcher = () => {
const notity = useNotify();
const { refetch, data } = useListContext();
useSubscribeToRecordList(event => {
switch (event.type) {
case 'created': {
notity('New movie created');
refetch();
break;
}
case 'updated': {
if (data.find(record => record.id === event.payload.ids[0])) {
notity(`Movie #${event.payload.ids[0]} updated`);
refetch();
}
break;
}
case 'deleted': {
if (data.find(record => record.id === event.payload.ids[0])) {
notity(`Movie #${event.payload.ids[0]} deleted`);
refetch();
}
break;
}
}
});
return null;
};
const MovieList = () => (
<ListBase>
{/* The list view*/}
<ListWatcher />
</ListBase>
);
import React from "react";
import { useNotify, useListContext } from "ra-core";
import { useSubscribeToRecordList } from "@react-admin/ra-core-ee";
const ListWatcher = () => {
const notity = useNotify();
const { refetch, data } = useListContext();
useSubscribeToRecordList((event) => {
switch (event.type) {
case "created": {
notity("New movie created");
refetch();
break;
}
case "updated": {
if (data.find((record) => record.id === event.payload.ids[0])) {
notity(`Movie #${event.payload.ids[0]} updated`);
refetch();
}
break;
}
case "deleted": {
if (data.find((record) => record.id === event.payload.ids[0])) {
notity(`Movie #${event.payload.ids[0]} deleted`);
refetch();
}
break;
}
}
});
return null;
};
const MovieList = () => (
<ListBase>
{/* The list view*/}
<ListWatcher />
</ListBase>
);
Parameters
Prop | Required | Type | Default | Description |
---|---|---|---|---|
callback |
Required | function |
- | The callback function to execute when an event is published on the topic. |
resource |
Optional | string |
- | The resource to subscribe to. Defaults to the resource in the ResourceContext . |
options |
Optional | object |
- | The subscription options. |
callback
Whenever an event is published on the resource/[resource]
topic, the function passed as the first argument will be called with the event as a parameter.
const notity = useNotify();
const { refetch, data } = useListContext();
useSubscribeToRecordList(event => {
switch (event.type) {
case 'created': {
notity('New movie created');
refetch();
break;
}
case 'updated': {
if (data.find(record => record.id === event.payload.ids[0])) {
notity(`Movie #${event.payload.ids[0]} updated`);
refetch();
}
break;
}
case 'deleted': {
if (data.find(record => record.id === event.payload.ids[0])) {
notity(`Movie #${event.payload.ids[0]} deleted`);
refetch();
}
break;
}
}
});
const notity = useNotify();
const { refetch, data } = useListContext();
useSubscribeToRecordList((event) => {
switch (event.type) {
case "created": {
notity("New movie created");
refetch();
break;
}
case "updated": {
if (data.find((record) => record.id === event.payload.ids[0])) {
notity(`Movie #${event.payload.ids[0]} updated`);
refetch();
}
break;
}
case "deleted": {
if (data.find((record) => record.id === event.payload.ids[0])) {
notity(`Movie #${event.payload.ids[0]} deleted`);
refetch();
}
break;
}
}
});
Tip: Memoize the callback using useCallback
to avoid unnecessary subscriptions/unsubscriptions.
const notity = useNotify();
const { refetch, data } = useListContext();
const callback = useCallback(
event => {
switch (event.type) {
case 'created': {
notity('New movie created');
refetch();
break;
}
case 'updated': {
if (data.find(record => record.id === event.payload.ids[0])) {
notity(`Movie #${event.payload.ids[0]} updated`);
refetch();
}
break;
}
case 'deleted': {
if (data.find(record => record.id === event.payload.ids[0])) {
notity(`Movie #${event.payload.ids[0]} deleted`);
refetch();
}
break;
}
}
},
[data, refetch, notity]
);
useSubscribeToRecordList(callback);
const notity = useNotify();
const { refetch, data } = useListContext();
const callback = useCallback(
(event) => {
switch (event.type) {
case "created": {
notity("New movie created");
refetch();
break;
}
case "updated": {
if (data.find((record) => record.id === event.payload.ids[0])) {
notity(`Movie #${event.payload.ids[0]} updated`);
refetch();
}
break;
}
case "deleted": {
if (data.find((record) => record.id === event.payload.ids[0])) {
notity(`Movie #${event.payload.ids[0]} deleted`);
refetch();
}
break;
}
}
},
[data, refetch, notity]
);
useSubscribeToRecordList(callback);
Just like for useSubscribe
, the callback function receives an unsubscribe
callback as its second argument. You can call it to unsubscribe from the topic after receiving a specific event.
options
The options
object can contain the following properties:
enabled
: Whether to subscribe or not. Defaults totrue
once
: Whether to unsubscribe after the first event. Defaults tofalse
.unsubscribeOnUnmount
: Whether to unsubscribe on unmount. Defaults totrue
.
See useSubscribe
for more details.
resource
useSubscribeToRecordList
reads the current resource from the ResourceContext
. You can provide the resource explicitly if you are not in such a context:
useSubscribeToRecordList(event => {
if (event.type === 'updated') {
notify('Post updated');
refresh();
}
}, 'posts');
useSubscribeToRecordList((event) => {
if (event.type === "updated") {
notify("Post updated");
refresh();
}
}, "posts");
useLock
useLock
is a low-level hook that returns a callback to call dataProvider.lock()
, leveraging react-query's useMutation
.
const [lock, { isLoading, error }] = useLock(
resource,
{ id, identity, meta },
options
);
const [lock, { isLoading, error }] = useLock(resource, { id, identity, meta }, options);
The payload is an object with the following properties:
id
: the record id (e.g.123
)identity
: an identifier (string or number) corresponding to the identity of the locker (e.g.'julien'
). This usually comes fromauthProvider.getIdentity()
.meta
: an object that will be forwarded to the dataProvider (optional)
The optional options
argument is passed to react-query's useMutation
hook.
For most use cases, you won't need to call the useLock
hook directly. Instead, you should use the useLockOnMount
or useLockOnCall
orchestration hooks, which are responsible for calling useLock
and useUnlock
.
useUnlock
useUnlock
is a low-level hook that returns a callback to call dataProvider.unlock()
, leveraging react-query's useMutation
.
const [unlock, { isLoading, error }] = useUnlock(
resource,
{ id, identity, meta },
options
);
const [unlock, { isLoading, error }] = useUnlock(resource, { id, identity, meta }, options);
The payload is an object with the following properties:
id
: the record id (e.g.123
)identity
: an identifier (string or number) corresponding to the identity of the locker (e.g.'julien'
). This usually comes fromauthProvider.getIdentity()
meta
: an object that will be forwarded to the dataProvider (optional)
The optional options
argument is passed to react-query's useMutation
hook.
useGetLock
Gets the lock status for a record. It calls dataProvider.getLock()
on mount.
const { data, isLoading } = useGetLock(resource, { id });
const { data, isLoading } = useGetLock(resource, { id });
Parameters description:
resource
: the resource name (e.g.'posts'
)params
: an object with the following properties:id
: the record id (e.g.123
)meta
: Optional. an object that will be forwarded to the dataProvider (optional)
Here is a form toolbar that displays the lock status of the current record:
const FormToolbar = () => {
const resource = useResourceContext();
const record = useRecordContext();
const { isLoading: identityLoading, identity } = useGetIdentity();
const { isLoading: lockLoading, data: lock } = useGetLock(resource, {
id: record.id,
});
if (identityLoading || lockLoading) {
return null;
}
const isLockedByOtherUser = lock?.identity !== identity.id;
return (
<div className="flex items-center gap-4">
<button type="submit" disabled={isLockedByOtherUser}>Save</button>
{isLockedByOtherUser && (
<span>
{`This record is locked by another user: ${lock?.dentity}.`}
</span>
)}
</div>
);
};
const FormToolbar = () => {
const resource = useResourceContext();
const record = useRecordContext();
const { isLoading: identityLoading, identity } = useGetIdentity();
const { isLoading: lockLoading, data: lock } = useGetLock(resource, {
id: record.id,
});
if (identityLoading || lockLoading) {
return null;
}
const isLockedByOtherUser = lock?.identity !== identity.id;
return (
<div className="flex items-center gap-4">
<button type="submit" disabled={isLockedByOtherUser}>
Save
</button>
{isLockedByOtherUser && <span>{`This record is locked by another user: ${lock?.dentity}.`}</span>}
</div>
);
};
useGetLockLive
Use the useGetLockLive()
hook to get the lock status in real time. This hook calls dataProvider.getLock()
for the current record on mount, and subscribes to live updates on the lock/[resource]/[id]
topic.
This means that if the lock is acquired or released by another user while the current user is on the page, the return value will be updated.
import { useGetLockLive } from '@react-admin/ra-core-ee';
const LockStatus = () => {
const { data: lock } = useGetLockLive();
const { identity } = useGetIdentity();
if (!lock) return <span>No lock</span>;
if (lock.identity === identity?.id) return <span>Locked by you</span>;
return <span>Locked by {lock.identity}</span>;
};
import { useGetLockLive } from "@react-admin/ra-core-ee";
const LockStatus = () => {
const { data: lock } = useGetLockLive();
const { identity } = useGetIdentity();
if (!lock) return <span>No lock</span>;
if (lock.identity === identity?.id) return <span>Locked by you</span>;
return <span>Locked by {lock.identity}</span>;
};
useGetLockLive
reads the current resource and record id from the ResourceContext
and RecordContext
. You can provide them explicitly if you are not in such a context:
const { data: lock } = useGetLockLive('posts', { id: 123 });
const { data: lock } = useGetLockLive("posts", { id: 123 });
useGetLocks
Get all the locks for a given resource. Calls dataProvider.getLocks()
on mount.
// simple Usage
const { data } = useGetLocks('posts');
// simple Usage
const { data } = useGetLocks("posts");
Here is how to use it in a custom list, to disable edit and delete buttons for locked records:
import { WithListContext, useRecordContext } from 'ra-core';
import { useGetLocks, type Lock } from '@react-admin/ra-core-ee';
import { DeleteButton } from '@components/ui/DeleteButton';
import { LockableEditButton } from '@components/ui/DeleteButton';
const MyPostGrid = () => {
const resource = useResourceContext();
const { data: locks } = useGetLocks(resource);
return (
<ul>
<WithListContext
render={({ data, isPending }) => isPending ? null : (
<li className="flex justify-space-between">
<MyPostTitle locks={locks} />
<MyPostActions locks={locks} />
</li>
)}
/>
</ul>
);
};
const MyPostTitle = ({ locks }: { locks: Lock[] }) => {
const record = useRecordContext();
const lock = locks.find(l => l.recordId === record.id);
return (
<div className="flex gap-4">
<WithRecord label="title" render={record => <span>{record.title}</span>} />} />
{lock && (
<span style={{ color: 'red' }}>
{` (Locked by ${lock.identity})`}
</span>
)}
</div>
);
};
const MyPostActions = ({ locks }: { locks: Lock[] }) => {
const record = useRecordContext();
const locked = locks.find(l => l.recordId === record.id);
return (
<div className="flex gap-4">
<DeleteButton disabled={!!locked} />
<LockableEditButton disabled={!!locked} />
</div>
);
};
import { WithListContext, useRecordContext } from "ra-core";
import { useGetLocks } from "@react-admin/ra-core-ee";
import { DeleteButton } from "@components/ui/DeleteButton";
import { LockableEditButton } from "@components/ui/DeleteButton";
const MyPostGrid = () => {
const resource = useResourceContext();
const { data: locks } = useGetLocks(resource);
return (
<ul>
<WithListContext
render={({ data, isPending }) =>
isPending ? null : (
<li className="flex justify-space-between">
<MyPostTitle locks={locks} />
<MyPostActions locks={locks} />
</li>
)
}
/>
</ul>
);
};
const MyPostTitle = ({ locks }) => {
const record = useRecordContext();
const lock = locks.find((l) => l.recordId === record.id);
return (
<div className="flex gap-4">
<WithRecord label="title" render={(record) => <span>{record.title}</span>} />} />
{lock && <span style={{ color: "red" }}>{` (Locked by ${lock.identity})`}</span>}
</div>
);
};
const MyPostActions = ({ locks }) => {
const record = useRecordContext();
const locked = locks.find((l) => l.recordId === record.id);
return (
<div className="flex gap-4">
<DeleteButton disabled={!!locked} />
<LockableEditButton disabled={!!locked} />
</div>
);
};
useGetLocksLive
Use the useGetLocksLive
hook to get the locks in real time. This hook calls dataProvider.getLocks()
for the current resource on mount, and subscribes to live updates on the lock/[resource]
topic.
This means that if a lock is acquired or released by another user while the current user is on the page, the return value will be updated.
import { useRecordContext } from 'ra-core';
import { useGetLocksLive } from '@react-admin/ra-core-ee';
import { Lock } from 'lucide-react';
export const LockField = ({ locks }) => {
const record = useRecordContext();
if (!record) return null;
const lock = locks?.find(lock => lock.recordId === record?.id);
if (!lock) return <span className="w-4 h-4" />;
return <Lock className="w-4 h-4" />;
};
import { useRecordContext } from "ra-core";
import { Lock } from "lucide-react";
export const LockField = ({ locks }) => {
const record = useRecordContext();
if (!record) return null;
const lock = locks?.find((lock) => lock.recordId === record?.id);
if (!lock) return <span className="w-4 h-4" />;
return <Lock className="w-4 h-4" />;
};
useGetLocksLive
reads the current resource from the ResourceContext
. You can provide it explicitly if you are not in such a context:
const { data: locks } = useGetLocksLive('posts');
const { data: locks } = useGetLocksLive("posts");
useLockCallbacks
This utility hook allows to easily get the callbacks to lock and unlock a record, as well as the current lock status.
Usage
Use this hook e.g. to build a lock button:
import { useLockCallbacks } from '@react-admin/ra-core-ee';
import { LoaderCircle, Lock } from 'lucide-react';
export const LockButton = () => {
const {
lock,
isLocked,
isLockedByCurrentUser,
isPending,
isLocking,
isUnlocking,
doLock,
doUnlock,
} = useLockCallbacks();
if (isPending) {
return null;
}
return isLocked ? (
isLockedByCurrentUser ? (
<button
disabled={isUnlocking}
onClick={(e: React.MouseEvent<HTMLButtonElement>) => {
e.stopPropagation();
doUnlock();
}}
title="Locked by you, click to unlock"
>
{isUnlocking ? (
<LoaderCircle className="w-4 h-4 animate-spin" />
) : (
<Lock className="w-4 h-4" />
)}
</button>
) : (
<Lock title={`Locked by another user: ${lock?.identity}`} />
)
) : (
<button
disabled={isLocking}
onClick={(e: React.MouseEvent<HTMLButtonElement>) => {
e.stopPropagation();
doLock();
}}
title="Record is unlocked, click to lock"
>
{isLocking ? <LoaderCircle className="w-4 h-4 animate-spin" /> : <LockOpenIcon className="w-4 h-4" />}
</button>
);
};
import { useLockCallbacks } from "@react-admin/ra-core-ee";
import { LoaderCircle, Lock } from "lucide-react";
export const LockButton = () => {
const { lock, isLocked, isLockedByCurrentUser, isPending, isLocking, isUnlocking, doLock, doUnlock } =
useLockCallbacks();
if (isPending) {
return null;
}
return isLocked ? (
isLockedByCurrentUser ? (
<button
disabled={isUnlocking}
onClick={(e) => {
e.stopPropagation();
doUnlock();
}}
title="Locked by you, click to unlock"
>
{isUnlocking ? <LoaderCircle className="w-4 h-4 animate-spin" /> : <Lock className="w-4 h-4" />}
</button>
) : (
<Lock title={`Locked by another user: ${lock?.identity}`} />
)
) : (
<button
disabled={isLocking}
onClick={(e) => {
e.stopPropagation();
doLock();
}}
title="Record is unlocked, click to lock"
>
{isLocking ? <LoaderCircle className="w-4 h-4 animate-spin" /> : <LockOpenIcon className="w-4 h-4" />}
</button>
);
};
You can also leverage this hook as a quick way to access the lock status of the current record:
import { useLockCallbacks } from '@react-admin/ra-core-ee';
export const MyToolbar = () => {
const { isLockedByCurrentUser } = useLockCallbacks();
return (
<div>
<button type="submit" disabled={!isLockedByCurrentUser}>Save</button>
</div>
);
};
import { useLockCallbacks } from "@react-admin/ra-core-ee";
export const MyToolbar = () => {
const { isLockedByCurrentUser } = useLockCallbacks();
return (
<div>
<button type="submit" disabled={!isLockedByCurrentUser}>
Save
</button>
</div>
);
};
Parameters
useLockCallbacks
accepts a single options parameter, with the following properties:
Name | Required | Type | Default Value | Description |
---|---|---|---|---|
identity |
No | Identifier |
From AuthProvider.getIdentity() |
An identifier for the user who owns the lock. |
resource |
No | string |
From ResourceContext |
The resource name (e.g. 'posts' ). |
id |
No | Identifier |
From RecordContext |
The record id (e.g. 123 ). |
meta |
No | object |
- | Additional metadata forwarded to the dataProvider lock() , unlock() and getLock() calls. |
lockMutationOptions |
No | object |
- | react-query mutation options, used to customize the lock side-effects. |
unlockMutationOptions |
No | object |
- | react-query mutation options, used to customize the unlock side-effects. |
queryOptions |
No | object |
- | react-query query options, used to customize the lock query side-effects. |
You can call useLockCallbacks
with no parameter, and it will guess the resource and record id from the context (or the route):
const { isLocked, error, isLocking } = useLockCallbacks();
const { isLocked, error, isLocking } = useLockCallbacks();
Or you can provide them explicitly:
const { isLocked, error, isLocking } = useLockCallbacks({
resource: 'venues',
id: 123,
identity: 'John Doe',
});
const { isLocked, error, isLocking } = useLockCallbacks({
resource: "venues",
id: 123,
identity: "John Doe",
});
Return value
useLockCallbacks
returns an object with the following properties:
Name | Type | Description |
---|---|---|
isLocked |
boolean |
Whether the record is currently locked (possibly by another user) or not. |
isLockedByCurrentUser |
boolean |
Whether the record is locked by the current user or not. |
lock |
object |
The lock data. |
error |
object |
The error object if any of the mutations or the query fails. |
isPending |
boolean |
Whether the lock query is in progress. |
isLocking |
boolean |
Whether the lock mutation is in progress. |
isUnlocking |
boolean |
Whether the unlock mutation is in progress. |
doLock |
function |
A callback to manually lock the record. |
doUnlock |
function |
A callback to manually unlock the record. |
doLockAsync |
function |
A callback to manually lock the record asynchronously. |
doUnlockAsync |
function |
A callback to manually unlock the record asynchronously. |
lockQuery |
object |
The react-query query object for the lock status. |
lockMutation |
object |
The react-query mutation object for the lock mutation. |
unlockMutation |
object |
The react-query mutation object for the unlock mutation. |
useLockOnMount
This hook locks the current record on mount.
useLockOnMount
calls dataProvider.lock()
on mount and dataProvider.unlock()
on unmount to lock and unlock the record. It relies on authProvider.getIdentity()
to get the identity of the current user. It guesses the current resource
and recordId
from the context (or the route) if not provided.
Usage
Use this hook e.g. in an <Edit>
component to lock the record so that it only accepts updates from the current user.
import { EditBase, Form } from 'ra-core';
import { useLockOnMount } from '@react-admin/ra-core-ee';
const LockStatus = () => {
const { isLocked, error, isLoading } = useLockOnMount();
return (
<div>
{isLoading && <p>Locking post...</p>}
{error && (
<p>
<div>Failed to lock</div>
<div>Someone else is probably already locking it.</div>
</p>
)}
{isLocked && (
<p>
<div>Post locked</div>
<div>Only you can edit it.</div>
</p>
)}
</div>
);
};
const PostEdit = () => (
<EditBase>
<PostAside />
{/* The edit form*/}
</EditBase>
);
import { EditBase } from "ra-core";
import { useLockOnMount } from "@react-admin/ra-core-ee";
const LockStatus = () => {
const { isLocked, error, isLoading } = useLockOnMount();
return (
<div>
{isLoading && <p>Locking post...</p>}
{error && (
<p>
<div>Failed to lock</div>
<div>Someone else is probably already locking it.</div>
</p>
)}
{isLocked && (
<p>
<div>Post locked</div>
<div>Only you can edit it.</div>
</p>
)}
</div>
);
};
const PostEdit = () => (
<EditBase>
<PostAside />
{/* The edit form*/}
</EditBase>
);
Note: If users close their tab/browser when on a page with a locked record, useLockOnMount
will block the navigation and show a notification until the record is unlocked. Hence it's a good practice to give them a way to unlock the record manually, e.g. by using the doUnlock
callback returned by the hook or the <LockStatusBase>
component.
Parameters
useLockOnMount
accepts a single options parameter, with the following properties (all optional):
identity
: An identifier (string or number) corresponding to the identity of the locker (e.g.'julien'
). This could be an authentication token for instance. Falls back to the identifier of the identity returned by theAuthProvider.getIdentity()
function.resource
: The resource name (e.g.'posts'
). The hook uses theResourceContext
if not provided.id
: The record id (e.g.123
). The hook uses theRecordContext
if not provided.meta
: An object that will be forwarded to thedataProvider.lock()
calllockMutationOptions
:react-query
mutation options, used to customize the lock side-effects for instanceunlockMutationOptions
:react-query
mutation options, used to customize the unlock side-effects for instance
You can call useLockOnMount
with no parameter, and it will guess the resource and record id from the context (or the route):
const { isLocked, error, isLoading } = useLockOnMount();
const { isLocked, error, isLoading } = useLockOnMount();
Or you can provide them explicitly:
const { isLocked, error, isLoading } = useLockOnMount({
resource: 'venues',
id: 123,
identity: 'John Doe',
});
const { isLocked, error, isLoading } = useLockOnMount({
resource: "venues",
id: 123,
identity: "John Doe",
});
Tip: If the record can't be locked because another user is already locking it, you can use react-query
's retry feature to try again later:
const { isLocked, error, isLoading } = useLockOnMount({
lockMutationOptions: {
// retry every 5 seconds, until the lock is acquired
retry: true,
retryDelay: 5000,
},
});
const { isLocked, error, isLoading } = useLockOnMount({
lockMutationOptions: {
// retry every 5 seconds, until the lock is acquired
retry: true,
retryDelay: 5000,
},
});
Return value
useLockOnMount
returns an object with the following properties:
isLocked
: Whether the record is successfully locked by this hook or not.isLockedByCurrentUser
: Whether the record is locked by the current user or not.lock
: The lock data.error
: The error object if the lock attempt failed.isLocking
: Whether the lock mutation is in progress.isUnlocking
: Whether the unlock mutation is in progress.doLock
: A callback to manually lock the record.doUnlock
: A callback to manually unlock the record.doLockAsync
: A callback to manually lock the record asynchronously.doUnlockAsync
: A callback to manually unlock the record asynchronously.
useLockOnCall
Get a callback to lock a record and get a mutation state.
useLockOnCall
calls dataProvider.lock()
when the callback is called. It relies on authProvider.getIdentity()
to get the identity of the current user. It guesses the current resource
and recordId
from the context (or the route) if not provided. It releases the lock when the component unmounts by calling dataProvider.unlock()
.
Usage
Use this hook in a toolbar, to let the user lock the record manually.
import { EditBase } from 'ra-core';
import { useLockOnMount } from '@react-admin/ra-core-ee';
import { Alert, AlertTitle, Box, Button } from '@material-ui/core';
const LockStatus = () => {
const [doLock, { data, error, isLoading }] = useLockOnCall();
return (
<div>
{isLoading ? (
<div>Locking post...</div>
) : error ? (
<div>
<div>Failed to lock</div>
<div>Someone else is probably already locking it.</div>
</div>
) : data ? (
<div>
<div>Post locked</div>
<div>Only you can edit it.</div>
</div>
) : (
<button onClick={() => { doLock(); }}>
Lock post
</button>
)}
</div>
);
};
const PostEdit = () => (
<EditBase>
<PostAside />
{/* The edit form*/}
</EditBase>
);
import { EditBase } from "ra-core";
const LockStatus = () => {
const [doLock, { data, error, isLoading }] = useLockOnCall();
return (
<div>
{isLoading ? (
<div>Locking post...</div>
) : error ? (
<div>
<div>Failed to lock</div>
<div>Someone else is probably already locking it.</div>
</div>
) : data ? (
<div>
<div>Post locked</div>
<div>Only you can edit it.</div>
</div>
) : (
<button
onClick={() => {
doLock();
}}
>
Lock post
</button>
)}
</div>
);
};
const PostEdit = () => (
<EditBase>
<PostAside />
{/* The edit form*/}
</EditBase>
);
Note: If users close their tab/browser when on a page with a locked record, useLockOnCall
will block the navigation and show a notification until the record is unlocked. Hence it's a good practice to give them a way to unlock the record manually, e.g. by using the doUnlock
callback returned by the useLockCallbacks
hook or the <LockStatusBase>
component.
Parameters
useLockOnCall
accepts a single options parameter, with the following properties (all optional):
identity
: An identifier (string or number) corresponding to the identity of the locker (e.g.'julien'
). This could be an authentication token for instance. Falls back to the identifier of the identity returned by theAuthProvider.getIdentity()
function.resource
: The resource name (e.g.'posts'
). The hook uses theResourceContext
if not provided.id
: The record id (e.g.123
). The hook uses theRecordContext
if not provided.meta
: An object that will be forwarded to thedataProvider.lock()
calllockMutationOptions
:react-query
mutation options, used to customize the lock side-effects for instanceunlockMutationOptions
:react-query
mutation options, used to customize the unlock side-effects for instance
const LockButton = ({ resource, id, identity }) => {
const [doLock, lockMutation] = useLockOnCall({ resource, id, identity });
return (
<button onClick={() => {doLock();}} disabled={lockMutation.isLoading}>
Lock
</button>
);
};
const LockButton = ({ resource, id, identity }) => {
const [doLock, lockMutation] = useLockOnCall({ resource, id, identity });
return (
<button
onClick={() => {
doLock();
}}
disabled={lockMutation.isLoading}
>
Lock
</button>
);
};
useGetListLive
Alternative to useGetList
that subscribes to live updates on the record list.
import { useGetListLive } from '@react-admin/ra-core-ee';
const LatestNews = () => {
const { data, total, isLoading, error } = useGetListLive('posts', {
pagination: { page: 1, perPage: 10 },
sort: { field: 'published_at', order: 'DESC' },
});
if (isLoading) {
return <div>Loading...</div>;
}
if (error) {
return <p>ERROR</p>;
}
return (
<ul>
{data.map(item => (
<li key={item.id}>{item.title}</li>
))}
</ul>
);
};
import { useGetListLive } from "@react-admin/ra-core-ee";
const LatestNews = () => {
const { data, total, isLoading, error } = useGetListLive("posts", {
pagination: { page: 1, perPage: 10 },
sort: { field: "published_at", order: "DESC" },
});
if (isLoading) {
return <div>Loading...</div>;
}
if (error) {
return <p>ERROR</p>;
}
return (
<ul>
{data.map((item) => (
<li key={item.id}>{item.title}</li>
))}
</ul>
);
};
The hook will subscribe to live updates on the list of records (topic: resource/[resource]
) and will refetch the list when a new record is created, or an existing record is updated or deleted.
See the useGetList documentation for the full list of parameters and return type.
useGetOneLive
Alternative to useGetOne() that subscribes to live updates on the record
import { useRecordContext } from 'ra-core';
import { useGetOneLive } from '@react-admin/ra-core-ee';
const UserProfile = () => {
const record = useRecordContext();
const { data, isLoading, error } = useGetOneLive('users', {
id: record.id,
});
if (isLoading) {
return <div>Loading...</div>;
}
if (error) {
return <p>ERROR</p>;
}
return <div>User {data.username}</div>;
};
import { useRecordContext } from "ra-core";
import { useGetOneLive } from "@react-admin/ra-core-ee";
const UserProfile = () => {
const record = useRecordContext();
const { data, isLoading, error } = useGetOneLive("users", {
id: record.id,
});
if (isLoading) {
return <div>Loading...</div>;
}
if (error) {
return <p>ERROR</p>;
}
return <div>User {data.username}</div>;
};
The hook will subscribe to live updates on the record (topic: resource/[resource]/[id]
) and will refetch the record when it is updated or deleted.
See the useGetOne documentation for the full list of parameters and return type.
Components
<LockStatusBase>
Use the <LockStatusBase>
component to display the lock status of the record in the nearest RecordContext
:
import React from 'react';
import { Lock, LockOpen, LoaderCircle } from 'lucide-react';
import { LockStatusBase } from '@react-admin/ra-core-ee';
export const LockStatus = () => {
return (
<LockStatusBase
{...props}
render={({
doLock,
doUnlock,
isLocking,
isPending,
isUnlocking,
lockStatus,
message,
}) => {
if (isPending) {
return null;
}
if (lockStatus === 'lockedByUser') {
return (
<button
title={message}
disabled={isUnlocking}
onClick={(
e: React.MouseEvent<HTMLButtonElement>
) => {
e.stopPropagation();
doUnlock();
}}
>
{isUnlocking ? (
<LoaderCircle className="h-4 w-4 animate-spin" />
) : (
<Lock className="h-4 w-4" />
)}
</button>
);
}
if (lockStatus === 'lockedByAnotherUser') {
return (
<Lock className="h-4 w-4 text-error" />
);
}
if (lockStatus === 'unlocked') {
return (
<button
title={message}
disabled={isLocking}
onClick={(
e: React.MouseEvent<HTMLButtonElement>
) => {
e.stopPropagation();
doLock();
}}
color="warning"
>
{isLocking ? (
<LoaderCircle className="h-4 w-4 animate-spin" />
) : (
<LockOpen className="h-4 w-4" />
)}
</button>
);
}
return null;
}}
/>
);
};
import React from "react";
import { Lock, LockOpen, LoaderCircle } from "lucide-react";
import { LockStatusBase } from "@react-admin/ra-core-ee";
export const LockStatus = () => {
return (
<LockStatusBase
{...props}
render={({ doLock, doUnlock, isLocking, isPending, isUnlocking, lockStatus, message }) => {
if (isPending) {
return null;
}
if (lockStatus === "lockedByUser") {
return (
<button
title={message}
disabled={isUnlocking}
onClick={(e) => {
e.stopPropagation();
doUnlock();
}}
>
{isUnlocking ? (
<LoaderCircle className="h-4 w-4 animate-spin" />
) : (
<Lock className="h-4 w-4" />
)}
</button>
);
}
if (lockStatus === "lockedByAnotherUser") {
return <Lock className="h-4 w-4 text-error" />;
}
if (lockStatus === "unlocked") {
return (
<button
title={message}
disabled={isLocking}
onClick={(e) => {
e.stopPropagation();
doLock();
}}
color="warning"
>
{isLocking ? (
<LoaderCircle className="h-4 w-4 animate-spin" />
) : (
<LockOpen className="h-4 w-4" />
)}
</button>
);
}
return null;
}}
/>
);
};
In addition to the useLockCallbacks
parameters, <LockStatusBase>
accepts a render
prop. The function passed to the render
prop will be called with the result of the useLockCallbacks
hook.
I18N
This module uses specific translations for displaying notifications. As for all translations in react-admin, it's possible to customize the messages.
To create your own translations, you can use the TypeScript types to see the structure and see which keys are overridable.
Here is an example of how to customize translations in your app:
import polyglotI18nProvider from 'ra-i18n-polyglot';
import englishMessages from 'ra-language-english';
import frenchMessages from 'ra-language-french';
import {
raRealTimeLanguageEnglish,
raRealTimeLanguageFrench,
type RaRealTimeTranslationMessages,
} from '@react-admin/ra-core-ee';
import { CoreAdmin, mergeTranslations, type TranslationMessages as BaseTranslationMessages } from 'ra-core';
/* TranslationMessages extends the default translation
* Type from ra-core (BaseTranslationMessages)
* and the ra-realtime translation Type (RaRealTimeTranslationMessages)
*/
interface TranslationMessages
extends RaRealTimeTranslationMessages,
BaseTranslationMessages {}
const customEnglishMessages: TranslationMessages = mergeTranslations(
englishMessages,
raRealTimeLanguageEnglish,
{
'ra-realtime': {
notification: {
record: {
updated: 'Wow, this entry has been modified by a ghost',
deleted: 'Hey, a ghost has stolen this entry',
},
},
},
}
);
const i18nCustomProvider = polyglotI18nProvider(locale => {
if (locale === 'fr') {
return mergeTranslations(frenchMessages, raRealTimeLanguageFrench);
}
return customEnglishMessages;
}, 'en');
export const MyApp = () => (
<CoreAdmin i18nProvider={i18nCustomProvider}>
...
</CoreAdmin>
);
import polyglotI18nProvider from "ra-i18n-polyglot";
import englishMessages from "ra-language-english";
import frenchMessages from "ra-language-french";
import { raRealTimeLanguageEnglish, raRealTimeLanguageFrench } from "@react-admin/ra-core-ee";
import { CoreAdmin, mergeTranslations } from "ra-core";
const customEnglishMessages = mergeTranslations(englishMessages, raRealTimeLanguageEnglish, {
"ra-realtime": {
notification: {
record: {
updated: "Wow, this entry has been modified by a ghost",
deleted: "Hey, a ghost has stolen this entry",
},
},
},
});
const i18nCustomProvider = polyglotI18nProvider((locale) => {
if (locale === "fr") {
return mergeTranslations(frenchMessages, raRealTimeLanguageFrench);
}
return customEnglishMessages;
}, "en");
export const MyApp = () => <CoreAdmin i18nProvider={i18nCustomProvider}>...</CoreAdmin>;
Relationships
Many-To-Many Relationships
Developers usually store many-to-many relationships in databases using an associative table (also known as join table, junction table or cross-reference table). For instance, if a Book can have many Authors, and an Author can write several Books, the normalized way to store this relationship in a relational database uses an intermediate table book_authors
, as follows:
┌──────────────────┐ ┌──────────────┐ ┌───────────────┐
│ books │ │ book_authors │ │ authors │
│------------------│ │--------------│ │---------------│
│ id │───┐ │ id │ ┌──│ id │
│ title │ └──╼│ book_id │ │ │ first_name │
│ body │ │ author_id │╾──┘ │ last_name │
│ publication_date │ │ is_public │ │ date_of_birth │
└──────────────────┘ └──────────────┘ └───────────────┘
In the book_authors
table, book_id
and author_id
are both foreign keys to books
and authors
.
A REST API closely following this data model exposes the three resources /books
, /authors
, and /book_authors
. ra-relationships
components rely on the associative table without ever showing it to the end-user. From the end user's point of view, the associative table is an implementation detail.
Out of scope
If the associative table uses a composite primary key, then ra-relationships
does not work, as react-admin requires that all entities expose an identifier called id
. For example, if user permissions are seen as a many-to-many relationship, they can be modeled in a relational database as follows:
users user_permissions permissions
---------- ---------------- -----------------
login user_login key
password permission_key description
first_name
last_name
Here, the associative table uses a composite primary key made of the tuple (user_login, permission_key)
. To allow react-admin to use this associative table, the related API route (/user_permissions
) must include a unique id
field for each record (which can simply be the concatenation of the two foreign keys).
Also, if your REST API can present that relationship through a list of related record ids (e.g. author_ids
in books
and book_ids
in authors
), you don't need ra-relationships
. Just use <ReferenceArrayFieldBase>
and <ReferenceArrayInputBase>
, which are standard components in react-admin.
<ReferenceOneInputBase>
Use <ReferenceOneInputBase>
in an <EditBase>
or <CreateBase>
view to edit one-to-one relationships, e.g. to edit the details of a book in the book edition view.
Usage
Here is an example one-to-one relationship: a book
has at most one book_details
row associated to it.
┌─────────────┐ ┌──────────────┐
│ book │ │ book_details │
│-------------│ │--------------│
│ id │───┐ │ id │
│ title │ └──╼│ book_id │
└─────────────┘ │ year │
│ author │
│ country │
│ genre │
│ pages │
└──────────────┘
You probably want to let users edit the book details directly from the book Edition view (instead of having to go to the book details Edition view). <ReferenceOneInputBase>
allows to do that.
import { EditBase, Form } from 'ra-core';
import { TextInput, NumberInput } from 'my-react-admin-ui-library';
import { ReferenceOneInputBase } from '@react-admin/ra-core-ee';
const BookEdit = () => (
<EditBase mutationMode="optimistic">
<Form>
<TextInput source="title" />
<ReferenceOneInputBase reference="book_details" target="book_id">
<NumberInput source="year" />
<TextInput source="author" />
<TextInput source="country" />
<TextInput source="genre" />
<NumberInput source="pages" />
</ReferenceOneInputBase>
</Form>
</EditBase>
);
import { EditBase, Form } from "ra-core";
import { TextInput, NumberInput } from "my-react-admin-ui-library";
import { ReferenceOneInputBase } from "@react-admin/ra-core-ee";
const BookEdit = () => (
<EditBase mutationMode="optimistic">
<Form>
<TextInput source="title" />
<ReferenceOneInputBase reference="book_details" target="book_id">
<NumberInput source="year" />
<TextInput source="author" />
<TextInput source="country" />
<TextInput source="genre" />
<NumberInput source="pages" />
</ReferenceOneInputBase>
</Form>
</EditBase>
);
<ReferenceOneInputBase>
requires a reference
and a target
prop to know which entity to fetch, and one or more inputs as its children
to edit the related record.
<ReferenceOneInputBase>
persists the changes in the referenced record (book details in the above example) after persisting the changes in the main resource (book in the above example). This means that you can also use <ReferenceOneInputBase>
in Create views.
Tip: <ReferenceOneInputBase>
does not support optimistic nor undoable mutations. You will need to set mutationMode="pessimistic"
in the parent Edition component, as in the example above.
Props
Prop | Required | Type | Default | Description |
---|---|---|---|---|
target |
Required | string |
- | Target field carrying the relationship on the referenced resource, e.g. 'book_id' |
reference |
Required | string |
- | The name of the resource for the referenced records, e.g. 'book_details' |
children |
Optional | Element |
- | One or several input elements that accept a source prop |
defaultValue |
Optional | Object |
- | Default value for the related record (in case it does not yet exist) |
error |
Optional | Element |
- | The element to display when an error occurs while loading a reference |
filter |
Optional | Object |
- | Filters to use when fetching the related record, passed to `getManyReference() |
loading |
Optional | Element |
- | The element to display while loading a reference |
mutationOptions |
Optional | UseMutationOptions |
- | Options for the mutations (create and update ) |
render |
Optional | Function |
- | A function that returns the children to display. Takes precedence over children |
sort |
Optional | { field, order } |
{ field: 'id', order: 'ASC' } |
Sort order to use when fetching the related record, passed to `getManyReference() |
source |
Optional | string |
id |
Name of the field that carries the identity of the current record, used as origin for the relationship |
queryOptions |
Optional | UseQueryOptions |
- | Options for the queries (getManyReferences ) |
children
<ReferenceOneInputBase>
expects input components as its children, which will allow to edit the related record.
<ReferenceOneInputBase reference="book_details" target="book_id">
<NumberInput source="year" />
<TextInput source="author" />
<TextInput source="country" />
<TextInput source="genre" />
<NumberInput source="pages" />
</ReferenceOneInputBase>
defaultValue
<ReferenceOneInputBase>
allows to specify a default value for the related record. This is useful when the current record does not yet have a related record, and you want to pre-fill the related record with some default values.
<ReferenceOneInputBase
reference="book_details"
target="book_id"
defaultValue={{ author: 'Gustave Flaubert', year: 1857 }}
>
...
</ReferenceOneInputBase>
filter
<ReferenceOneInputBase>
allows to specify filters to use when fetching the related record. This can be useful when you need additional filters to select the related record.
<ReferenceOneInputBase
reference="book_details"
target="book_id"
filter={{ reviewed: true }}
>
...
</ReferenceOneInputBase>
error
To display a custom element when an error occurs while loading the reference, use the error
prop:
<ReferenceOneInputBase
reference="book_details"
target="book_id"
error={<MyError />}
>
...
</ReferenceOneInputBase>
loading
To display a custom element while loading the reference, use the loading
prop:
<ReferenceOneInputBase
reference="book_details"
target="book_id"
error={<MySkeleton />}
>
...
</ReferenceOneInputBase>
mutationOptions
Use the mutationOptions
prop to pass options to the dataProvider.create()
and dataProvider.update()
mutations.
For instance, to pass a custom meta:
<ReferenceOneInputBase
reference="book_details"
target="book_id"
mutationOptions={{ meta: { foo: 'bar' } }}
>
...
</ReferenceOneInputBase>
<ReferenceOneInputBase reference="book_details" target="book_id" mutationOptions={{ meta: { foo: "bar" } }}>
...
</ReferenceOneInputBase>;
reference
The name of the resource to fetch for the related records.
For instance, if you want to display the book_details
of a given book
, the reference
name should be book_details
:
<ReferenceOneInputBase reference="book_details" target="book_id">
...
</ReferenceOneInputBase>
render
<ReferenceOneInputBase>
accepts a render
function instead of children
if you want more control over what to display in all possible states.
<ReferenceOneInputBase
reference="book_details"
target="book_id"
render={({ isPending }) => isPending ? <Skeleton /> : (
<>
<NumberInput source="year" />
<TextInput source="author" />
<TextInput source="country" />
<TextInput source="genre" />
<NumberInput source="pages" />
</>
)}
/>
sort
<ReferenceOneInputBase>
allows to specify the sort options used when fetching the related record. This can be useful when the relation table does not have an id
column.
<ReferenceOneInputBase
reference="book_details"
target="book_id"
sort={{ field: '_id', order: 'DESC' }}
>
...
</ReferenceOneInputBase>
source
By default, <ReferenceManyInputBase>
fetches the reference
for which the target
field equals the current record id
. You can customize the field that carries the identity of the current record by setting the source
prop.
<ReferenceOneInputBase reference="book_details" target="book_id" source="_id">
...
</ReferenceOneInputBase>
target
Name of the field carrying the relationship on the referenced resource. For instance, if each book
is linked to a record in book_details
, and each book_details
exposes a book_id
field linking to the book
, the target
would be book_id
.
<ReferenceOneInputBase reference="book_details" target="book_id">
...
</ReferenceOneInputBase>
queryOptions
Use the queryOptions
prop to pass options to the dataProvider.getManyReferences()
query that fetches the possible choices.
For instance, to pass a custom meta:
<ReferenceOneInputBase
reference="book_details"
target="book_id"
queryOptions={{ meta: { foo: 'bar' } }}
>
...
</ReferenceOneInputBase>
<ReferenceOneInputBase reference="book_details" target="book_id" queryOptions={{ meta: { foo: "bar" } }}>
...
</ReferenceOneInputBase>;
Limitations
<ReferenceOneInputBase>
cannot be used inside an<ArrayInput>
or a<ReferenceManyInputBase>
.<ReferenceOneInputBase>
cannot have a<ReferenceManyInputBase>
or a<ReferenceManyToManyInputBase>
as one of its children.<ReferenceOneInputBase>
does not support server side validation.<ReferenceOneInputBase>
does not support optimistic nor undoable mutations.
Changing An Item's Value Programmatically
You can leverage react-hook-form
's setValue
method to change the reference record's value programmatically.
However you need to know the name
under which the inputs were registered in the form, and these names are dynamically generated by <ReferenceOneInputBase>
.
To get the name of a specific input, you can leverage the SourceContext
created by react-admin, which can be accessed using the useSourceContext
hook.
This context provides a getSource
function that returns the effective source
for an input in the current context, which you can use as input name for setValue
.
Here is an example where we leverage getSource
and setValue
to update some of the book details when the 'Update book details' button is clicked:
import { useSourceContext } from 'ra-core';
import { TextInput, NumberInput } from 'my-react-admin-ui-library';
import { ReferenceOneInputBase } from '@react-admin/ra-core-ee';
import { useFormContext } from 'react-hook-form';
const UpdateBookDetails = () => {
const sourceContext = useSourceContext();
const { setValue } = useFormContext();
const onClick = () => {
// Generate random values for year and pages
const year = 1000 + Math.floor(Math.random() * 1000);
const pages = 100 + Math.floor(Math.random() * 900);
setValue(sourceContext.getSource('year'), year);
setValue(sourceContext.getSource('pages'), pages);
};
return (
<Button onClick={onClick} size="small" sx={{ maxWidth: 200 }}>
Update book details
</Button>
);
};
const BookDetails = () => (
<ReferenceOneInputBase
reference="book_details"
target="book_id"
sort={sort}
filter={filter}
>
<div>
<NumberInput source="year" />
<TextInput source="author" />
<TextInput source="country" />
<TextInput source="genre" />
<NumberInput source="pages" />
<UpdateBookDetails />
</div>
</ReferenceOneInputBase>
);
import { useSourceContext } from "ra-core";
import { TextInput, NumberInput } from "my-react-admin-ui-library";
import { ReferenceOneInputBase } from "@react-admin/ra-core-ee";
import { useFormContext } from "react-hook-form";
const UpdateBookDetails = () => {
const sourceContext = useSourceContext();
const { setValue } = useFormContext();
const onClick = () => {
// Generate random values for year and pages
const year = 1000 + Math.floor(Math.random() * 1000);
const pages = 100 + Math.floor(Math.random() * 900);
setValue(sourceContext.getSource("year"), year);
setValue(sourceContext.getSource("pages"), pages);
};
return (
<Button onClick={onClick} size="small" sx={{ maxWidth: 200 }}>
Update book details
</Button>
);
};
const BookDetails = () => (
<ReferenceOneInputBase reference="book_details" target="book_id" sort={sort} filter={filter}>
<div>
<NumberInput source="year" />
<TextInput source="author" />
<TextInput source="country" />
<TextInput source="genre" />
<NumberInput source="pages" />
<UpdateBookDetails />
</div>
</ReferenceOneInputBase>
);
<ReferenceManyInputBase>
Use <ReferenceManyInputBase>
in an edition or creation views to edit one-to-many relationships, e.g. to edit the variants of a product in the product edition view.
<ReferenceManyInputBase>
fetches the related records, and renders them in a sub-form. When users add, remove of update related records, the <ReferenceManyInputBase>
component stores these changes locally. When the users actually submit the form, <ReferenceManyInputBase>
computes a diff with the existing relationship, and sends the related changes (additions, deletions, and updates) to the server.
Usage
An example one-to-many relationship can be found in ecommerce systems: a product has many variants.
┌───────────────┐ ┌──────────────┐
│ products │ │ variants │
│---------------│ │--------------│
│ id │───┐ │ id │
│ name │ └──╼│ product_id │
│ price │ │ sku │
│ category_id │ │ size │
└───────────────┘ │ color │
│ stock │
└──────────────┘
You probably want to let users edit variants directly from the product Edition view (instead of having to go to the variant Edition view). <ReferenceManyInputBase>
allows to do that.
import { EditBase, Form, ReferenceInputBase } from 'ra-core';
import {
AutocompleteInput,
TextInput,
NumberInput,
SelectInput,
SimpleFormIterator
} from 'my-react-admin-ui-library';
import { ReferenceManyInputBase } from '@react-admin/ra-core-ee';
const ProductEdit = () => (
<EditBase mutationMode="optimistic">
<Form>
<TextInput source="name" />
<NumberInput source="price" />
<ReferenceInputBase source="category_id" reference="categories">
<AutocompleteInput />
</ReferenceInputBase>
<ReferenceManyInputBase reference="variants" target="product_id">
<SimpleFormIterator>
<TextInput source="sku" />
<SelectInput source="size" choices={sizes} />
<SelectInput source="color" choices={colors} />
<NumberInput source="stock" defaultValue={0} />
</SimpleFormIterator>
</ReferenceManyInputBase>
</Form>
</EditBase>
);
<ReferenceManyInputBase>
requires a reference
and a target
prop to know which entity to fetch, and a child component (usually a <SimpleFormIterator>
) to edit the relationship.
<ReferenceManyInputBase>
persists the changes in the reference records (variants in the above example) after persisting the changes in the main resource (product in the above example). This means that you can also use <ReferenceManyInputBase>
in <CreateBase>
views.
Tip: <ReferenceManyInputBase>
cannot be used with undoable
mutations. You have to set mutationMode="optimistic"
or mutationMode="pessimistic"
in the parent <EditBase>
or <CreateBase>
, as in the example above.
Props
Prop | Required | Type | Default | Description |
---|---|---|---|---|
target |
Required | string |
- | Target field carrying the relationship on the referenced resource, e.g. 'user_id' |
reference |
Required | string |
- | The name of the resource for the referenced records, e.g. 'books' |
children |
Optional | Element |
- | One or several elements that render a list of records based on a ListContext |
defaultValue |
Optional | array |
- | Default value of the input. |
filter |
Optional | Object |
- | Filters to use when fetching the related records, passed to getManyReference() |
mutationOptions |
Optional | UseMutationOptions |
- | Options for the mutations (create , update and delete ) |
perPage |
Optional | number |
25 | Maximum number of referenced records to fetch |
queryOptions |
Optional | UseQueryOptions |
- | Options for the queries (getManyReferences ) |
rankSource |
Optional | string |
- | Name of the field used to store the rank of each item. When defined, it enables reordering of the items. |
sort |
Optional | { field, order } |
{ field: 'id', order: 'DESC' } |
Sort order to use when fetching the related records, passed to getManyReference() |
source |
Optional | string |
id |
Name of the field that carries the identity of the current record, used as origin for the relationship |
validate |
Optional | Function | array |
- | Validation rules for the array. See the Validation Documentation for details. |
children
<ReferenceManyInputBase>
creates an ArrayInputContext
, so it accepts the same type of children as <ArrayInput>
: a Form iterator. React-admin bundles one such iterator: <SimpleFormIterator>
. It renders one row for each related record, giving the user the ability to add, remove, or edit related records.
<ReferenceManyInputBase reference="variants" target="product_id">
<SimpleFormIterator>
<TextInput source="sku" />
<SelectInput source="size" choices={sizes} />
<SelectInput source="color" choices={colors} />
<NumberInput source="stock" defaultValue={0} />
</SimpleFormIterator>
</ReferenceManyInputBase>
Check out the <SimpleFormIterator>
documentation for more details.
defaultValue
When the current record has no related records, <ReferenceManyInputBase>
renders an empty list with an "Add" button to add related records.
You can use the defaultValue
prop to populate the list of related records in that case. It must be an array of objects.
<ReferenceManyInputBase
reference="variants"
target="product_id"
defaultValue={[
{ sku: 'SKU_1', size: 'S', color: 'black', stock: 0 },
{ sku: 'SKU_2', size: 'M', color: 'black', stock: 0 },
{ sku: 'SKU_3', size: 'L', color: 'black', stock: 0 },
{ sku: 'SKU_4', size: 'XL', color: 'black', stock: 0 },
]}
>
<SimpleFormIterator>
<TextInput source="sku" />
<SelectInput source="size" choices={sizes} />
<SelectInput source="color" choices={colors} />
<NumberInput source="stock" defaultValue={0} />
</SimpleFormIterator>
</ReferenceManyInputBase>
filter
You can filter the query used to populate the current values. Use the filter
prop for that.
<ReferenceManyInputBase
reference="variants"
target="product_id"
filter={{ is_published: true }}
>
...
</ReferenceManyInputBase>
perPage
By default, ra-core-ee restricts the possible values to 25 and displays no pagination control. You can change the limit by setting the perPage
prop:
<ReferenceManyInputBase reference="variants" target="product_id" perPage={10}>
...
</ReferenceManyInputBase>
rankSource
If the Form iterator you use as ReferenceManyInputBase
children (e.g. <SimpleFormIterator>
) provides controls to reorder the items in the list and the related records have a numeric rank field, you can enable the reordering feature by setting the rankSource
prop.
For example, if the variants have a rank
field, you can set the rankSource
prop like this:
<ReferenceManyInputBase
reference="variants"
target="product_id"
rankSource="rank"
>
<SimpleFormIterator>
<TextInput source="sku" />
<SelectInput source="size" choices={sizes} />
<SelectInput source="color" choices={colors} />
<NumberInput source="stock" defaultValue={0} />
</SimpleFormIterator>
</ReferenceManyInputBase>
Now the variants will be ordered by rank, and whenever the user changes the order of the items, <ReferenceManyInputBase>
will update the rank
field of each item accordingly.
reference
The name of the resource to fetch for the related records.
For instance, if you want to display the variants
of a given product
, the reference
name should be variants
:
<ReferenceManyInputBase reference="books" target="author_id">
...
</ReferenceManyInputBase>
sort
By default, related records appear ordered by id desc. You can change this order by setting the sort
prop (an object with field
and order
properties).
<ReferenceManyInputBase
reference="variants"
target="product_id"
sort={{ field: 'sku', order: 'ASC' }}
>
...
</ReferenceManyInputBase>
source
By default, <ReferenceManyInputBase>
fetches the references
for which the target
field equals the current record id
. You can customize the field that carries the identity of the current record by setting the source
prop.
<ReferenceManyInputBase reference="variants" target="product_id" source="_id">
...
</ReferenceManyInputBase>
target
Name of the field carrying the relationship on the referenced resource. For instance, if a product
has many variants
, and each variant resource exposes an product_id
field, the target
would be author_id
.
<ReferenceManyInputBase reference="variants" target="product_id">
...
</ReferenceManyInputBase>
validate
Just like regular inputs, you can use the validate
prop to define custom validation rules for the list of references.
import { minLength } from 'ra-core';
const ProductEdit = () => (
<EditBase mutationMode="optimistic">
<Form>
<TextInput source="name" />
<ReferenceInput source="category_id" reference="categories" />
<ReferenceManyInputBase
reference="variants"
target="product_id"
validate={[minLength(2, 'Please add at least 2 variants')]}
>
...
</ReferenceManyInputBase>
</Form>
</EditBase>
);
Limitations
<ReferenceManyInputBase>
cannot be used inside an<ArrayInputBase>
or a<ReferenceOneInputBase>
.<ReferenceManyInputBase>
cannot be used withundoable
mutations in a<Create>
view.<ReferenceManyInputBase>
cannot have a<ReferenceOneInputBase>
or a<ReferenceManyToManyInputBase>
as one of its children.<ReferenceManyInputBase>
does not support server side validation.
Changing An Item's Value Programmatically
You can leverage react-hook-form
's setValue
method to change an item's value programmatically.
However you need to know the name
under which the input was registered in the form, and this name is dynamically generated depending on the index of the item in the array.
To get the name of the input for a given index, you can leverage the SourceContext
created by react-admin, which can be accessed using the useSourceContext
hook.
This context provides a getSource
function that returns the effective source
for an input in the current context, which you can use as input name for setValue
.
Here is an example where we leverage getSource
and setValue
to prefill the email input when the 'Prefill email' button is clicked:
import { useSourceContext } from 'ra-core';
import { SimpleFormIterator, TextInput } from 'my-react-admin-ui-library';
import { ReferenceManyInputBase } from '@react-admin/ra-core-ee';
import { useFormContext } from 'react-hook-form';
const PrefillEmail = () => {
const sourceContext = useSourceContext();
const { setValue, getValues } = useFormContext();
const onClick = () => {
const firstName = getValues(sourceContext.getSource('first_name'));
const lastName = getValues(sourceContext.getSource('last_name'));
const email = `${
firstName ? firstName.toLowerCase() : ''
}.${lastName ? lastName.toLowerCase() : ''}@school.com`;
setValue(sourceContext.getSource('email'), email);
};
return (
<button onClick={onClick}>
Prefill email
</button>
);
};
const StudentsInput = () => (
<ReferenceManyInputBase
reference="students"
target="teacher_id"
sort={{ field: 'last_name', order: 'ASC' }}
>
<SimpleFormIterator>
<TextInput source="first_name" helperText={false} />
<TextInput source="last_name" helperText={false} />
<TextInput source="email" helperText={false} />
<PrefillEmail />
</SimpleFormIterator>
</ReferenceManyInputBase>
);
import { useSourceContext } from "ra-core";
import { SimpleFormIterator, TextInput } from "my-react-admin-ui-library";
import { ReferenceManyInputBase } from "@react-admin/ra-core-ee";
import { useFormContext } from "react-hook-form";
const PrefillEmail = () => {
const sourceContext = useSourceContext();
const { setValue, getValues } = useFormContext();
const onClick = () => {
const firstName = getValues(sourceContext.getSource("first_name"));
const lastName = getValues(sourceContext.getSource("last_name"));
const email = `${firstName ? firstName.toLowerCase() : ""}.${
lastName ? lastName.toLowerCase() : ""
}@school.com`;
setValue(sourceContext.getSource("email"), email);
};
return <button onClick={onClick}>Prefill email</button>;
};
const StudentsInput = () => (
<ReferenceManyInputBase reference="students" target="teacher_id" sort={{ field: "last_name", order: "ASC" }}>
<SimpleFormIterator>
<TextInput source="first_name" helperText={false} />
<TextInput source="last_name" helperText={false} />
<TextInput source="email" helperText={false} />
<PrefillEmail />
</SimpleFormIterator>
</ReferenceManyInputBase>
);
Tip: If you only need the item's index, you can leverage the useSimpleFormIteratorItem
hook instead.
<ReferenceManyToManyFieldBase>
This component fetches a list of referenced records by lookup in an associative table and passes the records down to its child component, which must be an iterator component.
Note: The <ReferenceManyToManyFieldBase>
cannot currently display multiple records with the same id from the end reference resource, even though they might have different properties in the associative table.
Usage
Let's imagine that you're writing an app managing concerts for artists. The data model features a many-to-many relationship between the bands
and venues
tables through a performances
associative table.
┌─────────┐ ┌──────────────┐ ┌───────────────┐
│ bands │ │ performances │ │ venues │
│---------│ │--------------│ │---------------│
│ id │───┐ │ id │ ┌──│ id │
│ name │ └──╼│ band_id │ │ │ name │
│ │ │ venue_id │╾──┘ │ location │
│ │ │ date │ │ │
└─────────┘ └──────────────┘ └───────────────┘
In this example, bands.id
matches performances.band_id
, and performances.venue_id
matches venues.id
.
To allow users see the venues
for a given band
in <SingleFieldList>
, wrap that component in <ReferenceManyToManyFieldBase>
where you define the relationship via the reference
, through
and using
props:
import React from 'react';
import { ShowBase } from 'ra-core';
import {
TextField,
DateField,
SingleFieldList,
ChipField,
} from 'my-react-admin-ui-library';
import { ReferenceManyToManyFieldBase } from '@react-admin/ra-core-ee';
export const BandShow = () => (
<ShowBase>
<div>
<TextField source="name" />
<ReferenceManyToManyFieldBase
reference="venues"
through="performances"
using="band_id,venue_id"
label="Performances"
>
<SingleFieldList>
<ChipField source="name" />
</SingleFieldList>
</ReferenceManyToManyFieldBase>
<EditButton />
</div>
</ShowBase>
);
import React from "react";
import { ShowBase } from "ra-core";
import { TextField, SingleFieldList, ChipField } from "my-react-admin-ui-library";
import { ReferenceManyToManyFieldBase } from "@react-admin/ra-core-ee";
export const BandShow = () => (
<ShowBase>
<div>
<TextField source="name" />
<ReferenceManyToManyFieldBase
reference="venues"
through="performances"
using="band_id,venue_id"
label="Performances"
>
<SingleFieldList>
<ChipField source="name" />
</SingleFieldList>
</ReferenceManyToManyFieldBase>
<EditButton />
</div>
</ShowBase>
);
Props
Prop | Required | Type | Default | Description |
---|---|---|---|---|
children |
Required | element |
- | An iterator element (e.g. <WithListContext> ). The iterator element usually has one or more child <Field> components. |
reference |
Required | string |
- | Name of the reference resource, e.g. 'venues' |
through |
Required | string |
- | Name of the resource for the associative table, e.g. 'performances' |
filter |
Optional | object |
{} |
Filter for the associative table (passed to the getManyReference() call) |
joinLimit |
Optional | number |
100 | Limit for the number of results fetched from the associative table. Should be greater than perPage |
perPage |
Optional | number |
25 | Limit the number of displayed result after getManyReference is called. Useful when using a pagination component. Should be smaller than joinLimit |
queryOptions |
Optional | UseQueryOptions |
- | Query options for the getMany and getManyReference calls |
sort |
Optional | { field: string, order: 'ASC' or 'DESC' } |
{ field: 'id', order: 'DESC' } |
Sort for the associative table (passed to the getManyReference() call) |
source |
Optional | string |
'id' |
Name of the field containing the identity of the main resource. Used determine the value to look for in the associative table. |
using |
Optional | string |
'[resource]_id,[reference]_id' |
Tuple (comma separated) of the two field names used as foreign keys, e.g 'band_id,venue_id'. The tuple should start with the field pointing to the resource, and finish with the field pointing to the reference |
children
<ReferenceManyToManyFieldBase>
expects an iterator component as child, i.e. a component working inside a ListContext
.
import React from 'react';
import { ShowBase, WithListContext } from 'ra-core';
import { ReferenceManyToManyFieldBase } from '@react-admin/ra-core-ee';
export const BandShow = () => (
<ShowBase>
<div>
<ReferenceManyToManyFieldBase
reference="venues"
through="performances"
using="band_id,venue_id"
label="Performances"
>
<WithListContext render={({ isPending, data }) => (
isPending ? (
<div>
{data.map(tag => (
<span key={tag.id} label={tag.name} />
))}
</div>
) : null
)}
/>
</ReferenceManyToManyFieldBase>
</div>
</ShowBase>
);
import React from "react";
import { ShowBase, WithListContext } from "ra-core";
import { ReferenceManyToManyFieldBase } from "@react-admin/ra-core-ee";
export const BandShow = () => (
<ShowBase>
<div>
<ReferenceManyToManyFieldBase
reference="venues"
through="performances"
using="band_id,venue_id"
label="Performances"
>
<WithListContext
render={({ isPending, data }) =>
isPending ? (
<div>
{data.map((tag) => (
<span key={tag.id} label={tag.name} />
))}
</div>
) : null
}
/>
</ReferenceManyToManyFieldBase>
</div>
</ShowBase>
);
filter
You can filter the records of the associative table (e.g. performances
) using the filter
prop. This filter
is passed to the getManyReference()
call.
<ReferenceManyToManyFieldBase
reference="venues"
through="performances"
using="band_id,venue_id"
filter={{ date: '2018-08-31' }}
>
{/* ... */}
</ReferenceManyToManyFieldBase>
<ReferenceManyToManyFieldBase
reference="venues"
through="performances"
using="band_id,venue_id"
filter={{ date: "2018-08-31" }}
>
{/* ... */}
</ReferenceManyToManyFieldBase>;
joinLimit
By default, <ReferenceManyToManyFieldBase>
fetches 100 entries in the join table (e.g. performances
). You can decrease or increase the number of entries fetched from the associative table by modifying the joinLimit
prop:
import { Pagination } from 'my-react-admin-ui-library';
<ReferenceManyToManyFieldBase
reference="venues"
through="performances"
using="band_id,venue_id"
joinLimit={50}
>
{/* ... */}
</ReferenceManyToManyFieldBase>;
<ReferenceManyToManyFieldBase reference="venues" through="performances" using="band_id,venue_id" joinLimit={50}>
{/* ... */}
</ReferenceManyToManyFieldBase>;
export {};
perPage
By default, <ReferenceManyToManyFieldBase>
displays at most 25 entries from the associative table (e.g. 25 performances
). You can change the limit by setting the perPage
prop:
<ReferenceManyToManyFieldBase
reference="venues"
through="performances"
using="band_id,venue_id"
perPage={10}
>
{/* ... */}
</ReferenceManyToManyFieldBase>
<ReferenceManyToManyFieldBase reference="venues" through="performances" using="band_id,venue_id" perPage={10}>
{/* ... */}
</ReferenceManyToManyFieldBase>;
queryOptions
Use the queryOptions
prop to customize the queries for getMany
and getManyReference
.
You can for instance use it to pass a custom meta to the dataProvider.
<ReferenceManyToManyFieldBase
reference="venues"
through="performances"
using="band_id,venue_id"
queryOptions={{ meta: { myParameter: 'value' } }}
>
{/* ... */}
</ReferenceManyToManyFieldBase>
<ReferenceManyToManyFieldBase
reference="venues"
through="performances"
using="band_id,venue_id"
queryOptions={{ meta: { myParameter: "value" } }}
>
{/* ... */}
</ReferenceManyToManyFieldBase>;
reference
The name of the target resource to fetch.
For instance, if you want to display the venues
of a given bands
, through performances
, the reference
name should be venues
:
<ReferenceManyToManyFieldBase
source="id"
reference="venues"
resource="bands"
through="performances"
>
{/* ... */}
</ReferenceManyToManyFieldBase>
<ReferenceManyToManyFieldBase source="id" reference="venues" resource="bands" through="performances">
{/* ... */}
</ReferenceManyToManyFieldBase>;
sort
By default, <ReferenceManyToManyFieldBase>
orders the possible values by id
desc for the associative table (e.g. performances
). You can change this order by setting the sort
prop (an object with field
and order
properties) to be applied to the associative resource.
<ReferenceManyToManyFieldBase
reference="venues"
through="performances"
using="band_id,venue_id"
sort={{ field: 'id', order: 'DESC' }}
>
{/* ... */}
</ReferenceManyToManyFieldBase>
<ReferenceManyToManyFieldBase
reference="venues"
through="performances"
using="band_id,venue_id"
sort={{ field: "id", order: "DESC" }}
>
{/* ... */}
</ReferenceManyToManyFieldBase>;
source
By default, <ReferenceManyToManyFieldBase>
uses the id
field as target for the reference. If the foreign key points to another field of your record, you can select it with the source
prop
<ReferenceManyToManyFieldBase
source="_id"
reference="venues"
resource="bands"
through="performances"
>
{/* ... */}
</ReferenceManyToManyFieldBase>
<ReferenceManyToManyFieldBase source="_id" reference="venues" resource="bands" through="performances">
{/* ... */}
</ReferenceManyToManyFieldBase>;
through
You must specify the associative table name using the through
prop.
<ReferenceManyToManyFieldBase reference="venues" through="performances">
{/* ... */}
</ReferenceManyToManyFieldBase>
<ReferenceManyToManyFieldBase reference="venues" through="performances">
{/* ... */}
</ReferenceManyToManyFieldBase>;
using
You can specify the columns to use in the associative using
the using prop.
<ReferenceManyToManyFieldBase
reference="venues"
through="performances"
using="band_id,venue_id"
>
{/* ... */}
</ReferenceManyToManyFieldBase>
<ReferenceManyToManyFieldBase reference="venues" through="performances" using="band_id,venue_id">
{/* ... */}
</ReferenceManyToManyFieldBase>;
DataProvider Calls
<ReferenceManyToManyFieldBase>
fetches the dataProvider
twice in a row:
- once to get the records of the associative resource (
performances
in this case), using agetManyReference()
call - once to get the records of the reference resource (
venues
in this case), using agetMany()
call.
For instance, if the user displays the band of id 123
, <ReferenceManyToManyFieldBase>
first issues the following query to the dataProvider
:
dataProvider.getManyReference('performances', {
target: 'band_id',
id: 123,
});
Let's say that the dataProvider
returns the following response:
{
"data": [
{ "id": 667, "band_id": 123, "venue_id": 732 },
{ "id": 895, "band_id": 123, "venue_id": 874 }
{ "id": 901, "band_id": 123, "venue_id": 756 }
],
"total": 3
}
Then, <ReferenceManyToManyFieldBase>
issues a second query to the dataProvider
:
dataProvider.getMany('venues', {
ids: [732, 874, 756],
});
And receives the reference venues:
{
"data": [
{ "id": 732, "name": "Madison Square Garden" },
{ "id": 874, "name": "Yankee Stadium" }
{ "id": 874, "name": "Barclays Center" }
],
"total": 3
}
<ReferenceManyToManyInputBase>
This component allows adding or removing relationships between two resources sharing an associative table. The changes in the associative table are sent to the dataProvider when the user submits the form so that they can cancel the changes before submission.
Note: The <ReferenceManyToManyInputBase>
cannot currently display multiple records with the same id from the end reference resource even though they might have different properties in the associative table.
Usage
Let's imagine that you're writing an app managing concerts for artists. The data model features a many-to-many relationship between the bands
and venues
tables through a performances
associative table.
┌─────────┐ ┌──────────────┐ ┌───────────────┐
│ bands │ │ performances │ │ venues │
│---------│ │--------------│ │---------------│
│ id │───┐ │ id │ ┌──│ id │
│ name │ └──╼│ band_id │ │ │ name │
│ │ │ venue_id │╾──┘ │ location │
│ │ │ date │ │ │
└─────────┘ └──────────────┘ └───────────────┘
In this example, bands.id
matches performances.band_id
, and performances.venue_id
matches venues.id
.
To let users edit the venues
for given band
in an <AutocompleteArrayInput>
, wrap that input in a <ReferenceManyToManyInputBase>
where you define the relationship via the reference
, through
and using
props:
import { EditBase, Form } from 'ra-core';
import { AutocompleteArrayInput, TextInput } from 'my-react-admin-ui-library';
import { ReferenceManyToManyInputBase } from '@react-admin/ra-core-ee';
export const BandEdit = () => (
<EditBase mutationMode="optimistic">
<Form>
<TextInput source="name" />
<ReferenceManyToManyInputBase
reference="venues"
through="performances"
using="band_id,venue_id"
>
<AutocompleteArrayInput
label="Performances"
optionText="name"
/>
</ReferenceManyToManyInputBase>
</Form>
</EditBase>
);
import { EditBase, Form } from "ra-core";
import { AutocompleteArrayInput, TextInput } from "my-react-admin-ui-library";
import { ReferenceManyToManyInputBase } from "@react-admin/ra-core-ee";
export const BandEdit = () => (
<EditBase mutationMode="optimistic">
<Form>
<TextInput source="name" />
<ReferenceManyToManyInputBase reference="venues" through="performances" using="band_id,venue_id">
<AutocompleteArrayInput label="Performances" optionText="name" />
</ReferenceManyToManyInputBase>
</Form>
</EditBase>
);
<ReferenceManyToManyInputBase>
expects a child that is an input allowing to select multiple values as child - like <AutocompleteArrayInput>
in the example above.
Note that although all possible child components support a defaultValue
prop, it will only be applied on create views.
Tip: We don't recommend using <ReferenceManyToManyInputBase>
in an edition view that has its mutationMode
set to undoable
. Indeed, even if users cancel the main mutation, the changes in the associative table will still be applied.
Tip: If you need to edit the fields of the associative table (e.g. the date
in performances
), you can use a <ReferenceManyInputBase>
instead of <ReferenceManyToManyInputBase>
.
You will need to let users select the related record (venue
in the example above) via a <ReferenceInputBase>
:
import { EditBase, Form, ReferenceInputBase, required } from 'ra-core';
import {
AutocompleteArrayInput,
DateInput,
SelectInput,
SimpleFormIterator,
TextInput,
} from 'my-react-admin-ui-library';
import { ReferenceManyInputBase } from '@react-admin/ra-core-ee';
const BandEdit = () => (
<Edit mutationMode="optimistic">
<Form>
<TextInput source="name" />
<ReferenceManyInputBase reference="performances" target="band_id">
<SimpleFormIterator inline disableReordering>
<DateInput source="date" />
<ReferenceInputBase reference="venues" source="venue_id">
<SelectInput optionText="name" />
</ReferenceInputBase>
</SimpleFormIterator>
</ReferenceManyInputBase>
</Form>
</Edit>
);
import { Form, ReferenceInputBase } from "ra-core";
import { DateInput, SelectInput, SimpleFormIterator, TextInput } from "my-react-admin-ui-library";
import { ReferenceManyInputBase } from "@react-admin/ra-core-ee";
const BandEdit = () => (
<Edit mutationMode="optimistic">
<Form>
<TextInput source="name" />
<ReferenceManyInputBase reference="performances" target="band_id">
<SimpleFormIterator inline disableReordering>
<DateInput source="date" />
<ReferenceInputBase reference="venues" source="venue_id">
<SelectInput optionText="name" />
</ReferenceInputBase>
</SimpleFormIterator>
</ReferenceManyInputBase>
</Form>
</Edit>
);
Limitation: <ReferenceManyToManyInputBase>
cannot be used to filter a list.
Props
Prop | Required | Type | Default | Description |
---|---|---|---|---|
children |
Required | element |
- | A select array input element (e.g. <SelectArrayInput> ). |
reference |
Required | string |
- | Name of the reference resource, e.g. 'venues' |
through |
Required | string |
- | Name of the resource for the associative table, e.g. 'book_authors' |
filter |
Optional | object |
{} |
Filter for the associative table (passed to the getManyReference() call) |
filter Choices |
Optional | object |
{} |
Filter for the possible choices fetched from the reference table (passed to the getList() call) |
mutationOptions |
Optional | { meta, onError } |
- | Mutation options for the create and deleteMany calls. Only meta and onError are supported. |
perPage |
Optional | number |
25 | Limit for the number of results fetched from the associative table |
perPage Choices |
Optional | number |
25 | Limit for the number of possible choices fetched from the reference table |
queryOptions |
Optional | UseQueryOptions |
- | Query options for the getList , getMany and getManyReference calls |
sort |
Optional | { field: string, order: 'ASC' or 'DESC' } |
{ field: 'id', order: 'DESC' } |
Sort for the associative table (passed to the getManyReference() call) |
sort Choices |
Optional | { field: string, order: 'ASC' or 'DESC' } |
{ field: 'id', order: 'DESC' } |
Sort for the possible choices fetched from the reference table (passed to the getList() call) |
source |
Optional | string |
'id' |
Name of the field containing the identity of the main resource. Used determine the value to look for in the associative table. |
using |
Optional | string |
'([resource]_id,[reference]_id)' |
Tuple (comma separated) of the two field names used as foreign keys, e.g 'book_id,author_id'. The tuple should start with the field pointing to the resource, and finish with the field pointing to the reference |
children
<ReferenceManyToManyInputBase>
expects an select component as child, i.e. a component working inside a ChoiceContext
.
import { EditBase, Form, ReferenceInputBase, required } from 'ra-core';
import {
SelectArrayInput,
DateInput,
SelectInput,
SimpleFormIterator,
TextInput,
} from 'my-react-admin-ui-library';
import { ReferenceManyToManyInputBase } from '@react-admin/ra-core-ee';
const BandEdit = () => (
<Edit mutationMode="optimistic">
<Form>
<TextInput source="name" />
<ReferenceManyToManyInputBase
reference="venues"
through="performances"
using="band_id,venue_id"
filter={{ date: '2018-08-31' }}
>
<SelectArrayInput />
</ReferenceManyToManyInputBase>
</Form>
</Edit>
);
import { Form } from "ra-core";
import { SelectArrayInput, TextInput } from "my-react-admin-ui-library";
import { ReferenceManyToManyInputBase } from "@react-admin/ra-core-ee";
const BandEdit = () => (
<Edit mutationMode="optimistic">
<Form>
<TextInput source="name" />
<ReferenceManyToManyInputBase
reference="venues"
through="performances"
using="band_id,venue_id"
filter={{ date: "2018-08-31" }}
>
<SelectArrayInput />
</ReferenceManyToManyInputBase>
</Form>
</Edit>
);
filter
You can filter the records of the associative table (e.g. performances
) using the filter
prop. This filter
is passed to the getManyReference()
call.
<ReferenceManyToManyInputBase
reference="venues"
through="performances"
using="band_id,venue_id"
filter={{ date: '2018-08-31' }}
>
{/* ... */}
</ReferenceManyToManyInputBase>
<ReferenceManyToManyInputBase
reference="venues"
through="performances"
using="band_id,venue_id"
filter={{ date: "2018-08-31" }}
>
{/* ... */}
</ReferenceManyToManyInputBase>;
filterChoices
<ReferenceManyToManyInputBase>
displays a list of possible values from the reference table (e.g. venues
) as suggestions in the input. It uses the getList()
dataProvider call to fetch these possible values.
You can filter the possible values of the reference table using the filterChoices
prop. This filterChoices
is passed to the getList()
call.
<ReferenceManyToManyInputBase
reference="venues"
through="performances"
using="band_id,venue_id"
filterChoice={{ location: 'New York' }}
>
{/* ... */}
</ReferenceManyToManyInputBase>
<ReferenceManyToManyInputBase
reference="venues"
through="performances"
using="band_id,venue_id"
filterChoice={{ location: "New York" }}
>
{/* ... */}
</ReferenceManyToManyInputBase>;
mutationOptions
Use the mutationOptions
prop to customize the create
and deleteMany
mutations.
You can for instance use it to pass a custom meta to the dataProvider.
<ReferenceManyToManyInputBase
reference="venues"
through="performances"
using="band_id,venue_id"
mutationOptions={{ meta: { myParameter: 'value' } }}
>
{/* ... */}
</ReferenceManyToManyInputBase>
<ReferenceManyToManyInputBase
reference="venues"
through="performances"
using="band_id,venue_id"
mutationOptions={{ meta: { myParameter: "value" } }}
>
{/* ... */}
</ReferenceManyToManyInputBase>;
You can also use it to pass an onError
function as follows:
<ReferenceManyToManyInputBase
reference="venues"
through="performances"
using="band_id,venue_id"
mutationOptions={{
onError: (error, step, data) => console.warn({ error, step, data })
}}
>
{/* ... */}
</ReferenceManyToManyInputBase>
<ReferenceManyToManyInputBase
reference="venues"
through="performances"
using="band_id,venue_id"
mutationOptions={{
onError: (error, step, data) => console.warn({ error, step, data }),
}}
>
{/* ... */}
</ReferenceManyToManyInputBase>;
perPage
By default, <ReferenceManyToManyInputBase>
displays at most 25 entries from the associative table (e.g. 25 performances
). You can change the limit by setting the perPage
prop:
<ReferenceManyToManyInputBase
reference="venues"
through="performances"
using="band_id,venue_id"
perPage={10}
>
{/* ... */}
</ReferenceManyToManyInputBase>
<ReferenceManyToManyInputBase reference="venues" through="performances" using="band_id,venue_id" perPage={10}>
{/* ... */}
</ReferenceManyToManyInputBase>;
perPageChoices
<ReferenceManyToManyInputBase>
displays a list of possible values from the reference table (e.g. venues
) as suggestions in the input. It uses the getList()
dataProvider call to fetch these possible values.
By default, react-admin displays at most 25 possible values from the reference table (e.g. 25 venues
). You can change the limit by setting the perPageChoices
prop:
<ReferenceManyToManyInputBase
reference="venues"
through="performances"
using="band_id,venue_id"
perPageChoices={10}
>
{/* ... */}
</ReferenceManyToManyInputBase>
<ReferenceManyToManyInputBase reference="venues" through="performances" using="band_id,venue_id" perPageChoices={10}>
{/* ... */}
</ReferenceManyToManyInputBase>;
queryOptions
Use the queryOptions
prop to customize the queries for getList
, getMany
and getManyReference
.
You can for instance use it to pass a custom meta to the dataProvider.
<ReferenceManyToManyInputBase
reference="venues"
through="performances"
using="band_id,venue_id"
queryOptions={{ meta: { myParameter: 'value' } }}
>
{/* ... */}
</ReferenceManyToManyInputBase>
<ReferenceManyToManyInputBase
reference="venues"
through="performances"
using="band_id,venue_id"
queryOptions={{ meta: { myParameter: "value" } }}
>
{/* ... */}
</ReferenceManyToManyInputBase>;
reference
The name of the target resource to fetch.
For instance, if you want to display the venues of a given bands, through performances, the reference name should be venues:
<ReferenceManyToManyInputBase
source="id"
reference="venues"
resource="bands"
through="performances"
>
{/* ... */}
</ReferenceManyToManyInputBase>
<ReferenceManyToManyInputBase source="id" reference="venues" resource="bands" through="performances">
{/* ... */}
</ReferenceManyToManyInputBase>;
sort
By default, <ReferenceManyToManyInputBase>
orders the possible values by id
desc for the associative table (e.g. performances
). You can change this order by setting the sort
prop (an object with field
and order
properties) to be applied to the associative resource.
<ReferenceManyToManyInputBase
reference="venues"
through="performances"
using="band_id,venue_id"
sort={{ field: 'id', order: 'DESC' }}
>
{/* ... */}
</ReferenceManyToManyInputBase>
<ReferenceManyToManyInputBase
reference="venues"
through="performances"
using="band_id,venue_id"
sort={{ field: "id", order: "DESC" }}
>
{/* ... */}
</ReferenceManyToManyInputBase>;
sortChoices
By default, <ReferenceManyToManyInputBase>
orders the possible values by id
desc for the reference table (e.g. venues
). You can change this order by setting the sortChoices
prop (an object with field
and order
properties).
<ReferenceManyToManyInputBase
reference="venues"
through="performances"
using="band_id,venue_id"
sortChoices={{ field: 'id', order: 'DESC' }}
>
{/* ... */}
</ReferenceManyToManyInputBase>
<ReferenceManyToManyInputBase
reference="venues"
through="performances"
using="band_id,venue_id"
sortChoices={{ field: "id", order: "DESC" }}
>
{/* ... */}
</ReferenceManyToManyInputBase>;
source
By default, <ReferenceManyToManyInputBase>
uses the id
field as target for the reference. If the foreign key points to another field of your record, you can select it with the source
prop:
<ReferenceManyToManyInputBase
source="_id"
reference="venues"
resource="bands"
through="performances"
>
{/* ... */}
</ReferenceManyToManyInputBase>
<ReferenceManyToManyInputBase source="_id" reference="venues" resource="bands" through="performances">
{/* ... */}
</ReferenceManyToManyInputBase>;
through
You must specify the associative table name using the through
prop.
<ReferenceManyToManyInputBase reference="venues" through="performances">
{/* ... */}
</ReferenceManyToManyInputBase>
<ReferenceManyToManyInputBase reference="venues" through="performances">
{/* ... */}
</ReferenceManyToManyInputBase>;
using
You can specify the columns to use in the associative using the using
prop.
<ReferenceManyToManyInputBase
reference="venues"
through="performances"
using="band_id,venue_id"
>
{/* ... */}
</ReferenceManyToManyInputBase>
<ReferenceManyToManyInputBase reference="venues" through="performances" using="band_id,venue_id">
{/* ... */}
</ReferenceManyToManyInputBase>;
Limitations
<ReferenceManyToManyInputBase>
cannot be used inside an<ArrayInputBase>
, a<ReferenceOneInputBase>
or a<ReferenceManyInputBase>
.<ReferenceManyToManyInputBase>
does not support server side validation.
dataProvider
Calls
When rendered, <ReferenceManyToManyInputBase>
fetches the dataProvider
three times in a row:
- once to get the records of the associative resource (
performances
in this case), using agetManyReference()
call - once to get the records of the reference resource (
venues
in this case), using agetMany()
call. - once to get the possible values of the reference resource (
venues
in this case) to show as suggestions in the input, using agetList()
call
For instance, if the user edits the band of id 123
, <ReferenceManyToManyInputBase>
first issues the following query to the dataProvider
:
dataProvider.getManyReference('venues', {
target: 'band_id',
id: 123,
});
Let's say that the dataProvider
returns the following response:
{
"data": [
{ "id": 667, "band_id": 123, "venue_id": 732 },
{ "id": 895, "band_id": 123, "venue_id": 874 }
{ "id": 901, "band_id": 123, "venue_id": 756 }
],
"total": 3
}
Then, <ReferenceManyToManyInputBase>
issues a second query to the dataProvider
:
dataProvider.getMany('venues', {
ids: [732, 874, 756],
});
Which returns the following:
{
"data": [
{ "id": 732, "name": "Madison Square Garden" },
{ "id": 874, "name": "Yankee Stadium" }
{ "id": 874, "name": "Barclays Center" }
]
}
That's enough to display the current value in the input. But to display venues suggestions, the component makes a final call:
dataProvider.getList('venues', {
sort: { field: 'id', order: 'DESC' },
pagination: { page: 1, perPage: 25 },
filter: {},
});
{
"data": [
{ "id": 732, "name": "Madison Square Garden" },
{ "id": 874, "name": "Yankee Stadium" }
{ "id": 874, "name": "Barclays Center" }
...
],
"total": 32
}
And that's it for the display phase.
When the user submits the form, the save
function compares the value of the <ReferenceManyToManyInputBase>
(the list of relationships edited by the user) with the value previously returned by the dataProvider
. Using a diffing algorithm, it deduces a list of insertions and deletions in the associative table, that are executed all at once.
For instance, let's say that after displaying the venues 732 and 874 where bands 123 performs, the user removes venue 732, and adds venues 2 and 3. Upon submission, the dataProvider
will detect removals and additions, and send the following queries:
dataProvider.delete('performances', {
id: 667,
previousData: { id: 667, band_id: 123, venue_id: 732 },
});
dataProvider.create('performances', {
data: { band_id: 123, venue_id: 2 },
});
dataProvider.create('performances', {
data: { band_id: 123, venue_id: 3 },
});
I18N
This module uses specific translations for displaying notifications. As for all translations in react-admin, it's possible to customize the messages.
To create your own translations, you can use the TypeScript types to see the structure and see which keys are overridable.
Here is an example of how to customize translations in your app:
import polyglotI18nProvider from 'ra-i18n-polyglot';
import englishMessages from 'ra-language-english';
import frenchMessages from 'ra-language-french';
import {
raRelationshipsLanguageEnglish,
raRelationshipsLanguageFrench,
type RaRelationshipsTranslationMessages,
} from '@react-admin/ra-core-ee';
import { CoreAdmin, mergeTranslations, type TranslationMessages as BaseTranslationMessages } from 'ra-core';
/* TranslationMessages extends the default translation
* Type from ra-core (BaseTranslationMessages)
* and the ra-Relationships translation Type (RaRelationshipsTranslationMessages)
*/
interface TranslationMessages
extends RaRelationshipsTranslationMessages,
BaseTranslationMessages {}
const customEnglishMessages: TranslationMessages = mergeTranslations(
englishMessages,
raRelationshipsLanguageEnglish,
{
'ra-relationships': {
referenceManyToManyInput: {
saveError: 'Server error: your changes were not completely saved',
},
},
}
);
const i18nCustomProvider = polyglotI18nProvider(locale => {
if (locale === 'fr') {
return mergeTranslations(frenchMessages, raRealTimeLanguageFrench);
}
return customEnglishMessages;
}, 'en');
export const MyApp = () => (
<CoreAdmin i18nProvider={i18nCustomProvider}>
...
</CoreAdmin>
);
import polyglotI18nProvider from "ra-i18n-polyglot";
import englishMessages from "ra-language-english";
import frenchMessages from "ra-language-french";
import { raRelationshipsLanguageEnglish } from "@react-admin/ra-core-ee";
import { CoreAdmin, mergeTranslations } from "ra-core";
const customEnglishMessages = mergeTranslations(englishMessages, raRelationshipsLanguageEnglish, {
"ra-relationships": {
referenceManyToManyInput: {
saveError: "Server error: your changes were not completely saved",
},
},
});
const i18nCustomProvider = polyglotI18nProvider((locale) => {
if (locale === "fr") {
return mergeTranslations(frenchMessages, raRealTimeLanguageFrench);
}
return customEnglishMessages;
}, "en");
export const MyApp = () => <CoreAdmin i18nProvider={i18nCustomProvider}>...</CoreAdmin>;
CHANGELOG
v1.2.0
2025-09-30
- Import headless hooks from ra-relationships
v1.1.0
2025-09-19
- Import headless hooks and functions from ra-realtime
v1.0.0
2025-09-08
- Import headless hooks from ra-rbac