Skip to content

[Doc] Update Soft Delete documentation #10986

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Oct 14, 2025
Merged

[Doc] Update Soft Delete documentation #10986

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
6d64b43
[Doc] Update Soft Delete documentation
djhi Oct 10, 2025
1ea0872
Fix invalid link
djhi Oct 13, 2025
efca339
Reorganize navigation
djhi Oct 13, 2025
27b6fb3
Add setting up page
djhi Oct 13, 2025
3e15883
Improve documentation for headless usage
djhi Oct 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 76 additions & 19 deletions docs/DeletedRecordsList.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,24 +36,41 @@ That's enough to display the deleted records list, with functional simple filter

## Props

| Prop | Required | Type | Default | Description |
|----------------------------|----------|---------------------------------|------------------------------------------|--------------------------------------------------------------------------------------------------|
| `debounce` | Optional | `number` | `500` | The debounce delay in milliseconds to apply when users change the sort or filter parameters. |
| `children` | Optional | `Element` | `<Deleted Records Table>` | The component used to render the list of deleted records. |
| `detail Components` | Optional | `Record<string, ComponentType>` | - | The custom show components for each resource in the deleted records list. |
| `disable Authentication` | Optional | `boolean` | `false` | Set to `true` to disable the authentication check. |
| `disable SyncWithLocation` | Optional | `boolean` | `false` | Set to `true` to disable the synchronization of the list parameters with the URL. |
| `filter` | Optional | `object` | - | The permanent filter values. |
| `filter DefaultValues` | Optional | `object` | - | The default filter values. |
| `mutation Mode` | Optional | `string` | `'undoable'` | Mutation mode (`'undoable'`, `'pessimistic'` or `'optimistic'`). |
| `pagination` | Optional | `ReactElement` | `<Pagination>` | The pagination component to use. |
| `perPage` | Optional | `number` | `10` | The number of records to fetch per page. |
| `queryOptions` | Optional | `object` | - | The options to pass to the `useQuery` hook. |
| `resource` | Optional | `string` | - | The resource of deleted records to fetch and display |
| `sort` | Optional | `object` | `{ field: 'deleted_at', order: 'DESC' }` | The initial sort parameters. |
| `storeKey` | Optional | `string` or `false` | - | The key to use to store the current filter & sort. Pass `false` to disable store synchronization |
| `title` | Optional | `string | ReactElement | false` | - | The title to display in the App Bar. |
| `sx` | Optional | `object` | - | The CSS styles to apply to the component. |
| Prop | Required | Type | Default | Description |
|----------------------------|----------------|---------------------------------|------------------------------------------|--------------------------------------------------------------------------------------------------|
| `authLoading` | Optional | `ReactNode` | - | The component to render while checking for authentication and permissions. |
| `debounce` | Optional | `number` | `500` | The debounce delay in milliseconds to apply when users change the sort or filter parameters. |
| `children` | Optional | `Element` | `<DeletedRecordsTable>` | The component used to render the list of deleted records. |
| `detailComponents` | Optional | `Record<string, ComponentType>` | - | The custom show components for each resource in the deleted records list. |
| `disable Authentication` | Optional | `boolean` | `false` | Set to `true` to disable the authentication check. |
| `disable SyncWithLocation` | Optional | `boolean` | `false` | Set to `true` to disable the synchronization of the list parameters with the URL. |
| `empty` | Optional | `ReactNode` | - | The component to display when the list is empty. |
| `error` | Optional | `ReactNode` | - | The component to render when failing to load the list of records. |
| `filter` | Optional | `object` | - | The permanent filter values. |
| `filter DefaultValues` | Optional | `object` | - | The default filter values. |
| `loading` | Optional | `ReactNode` | - | The component to render while loading the list of records. |
| `mutation Mode` | Optional | `string` | `'undoable'` | Mutation mode (`'undoable'`, `'pessimistic'` or `'optimistic'`). |
| `offline` | Optional | `ReactNode` | `<Offline>` | The component to render when there is no connectivity and there is no data in the cache |
| `pagination` | Optional | `ReactElement` | `<Pagination>` | The pagination component to use. |
| `perPage` | Optional | `number` | `10` | The number of records to fetch per page. |
| `queryOptions` | Optional | `object` | - | The options to pass to the `useQuery` hook. |
| `resource` | Optional | `string` | - | The resource of deleted records to fetch and display |
| `sort` | Optional | `object` | `{ field: 'deleted_at', order: 'DESC' }` | The initial sort parameters. |
| `storeKey` | Optional | `string` or `false` | - | The key to use to store the current filter & sort. Pass `false` to disable store synchronization |
| `title` | Optional | `string | ReactElement | false` | - | The title to display in the App Bar. |
| `sx` | Optional | `object` | - | The CSS styles to apply to the component. |

## `authLoading`

By default, `<DeletedRecordsList>` renders `<Loading>` while checking for authentication and permissions. You can display a custom component via the `authLoading` prop:

```jsx
import { DeletedRecordsList } from '@react-admin/ra-soft-delete';

export const CustomDeletedRecords = () => (
<DeletedRecordsList authLoading={<p>Checking for permissions...</p>} />
);
```

## `children`

Expand Down Expand Up @@ -152,9 +169,21 @@ const DeletedRecordsWithoutSyncWithLocation = () => <DeletedRecordsList disableS
const DeletedRecordsSyncWithStore = () => <DeletedRecordsList disableSyncWithLocation storeKey="deletedRecordsListParams" />;
```

## `error`

By default, `<DeletedRecordsList>` renders the children when an error happens while loading the list of deleted records. You can render an error component via the `error` prop:

```jsx
import { DeletedRecordsList } from '@react-admin/ra-soft-delete';

export const CustomDeletedRecords = () => (
<DeletedRecordsList error={<p>Something went wrong while loading your posts!</p>} />
);
```

## `filter`: Permanent Filter

You can choose to always filter the list, without letting the user disable this filter - for instance to display only published posts. Write the filter to be passed to the data provider in the `filter` props:
You can choose to always filter the list, without letting the user disable this filter - for instance to display only published posts. Write the filter to be passed to the data provider in the `filter` prop:

{% raw %}
```tsx
Expand Down Expand Up @@ -184,6 +213,19 @@ const filterSentToDataProvider = { ...filterDefaultValues, ...filterChosenByUser
```
{% endraw %}

## `loading`

By default, `<DeletedRecordsList>` renders the children while loading the list of deleted records. You can display a component during this time via the `loading` prop:

```jsx
import { Loading } from 'react-admin';
import { DeletedRecordsList } from '@react-admin/ra-soft-delete';

export const CustomDeletedRecords = () => (
<DeletedRecordsList loading={<Loading />} />
);
```

## `mutationMode`

The `<DeletedRecordsList>` list exposes restore and delete permanently buttons, which perform "mutations" (i.e. they alter the data). React-admin offers three modes for mutations. The mode determines when the side effects (redirection, notifications, etc.) are executed:
Expand Down Expand Up @@ -212,6 +254,21 @@ const PessimisticDeletedRecords = () => (

**Tip**: When using any other mode than `undoable`, the `<DeletePermanentlyButton>` and `<RestoreButton>` display a confirmation dialog before calling the dataProvider.

## `offline`

By default, `<DeletedRecordsList>` renders the `<Offline>` component when there is no connectivity and there are no records in the cache yet for the current parameters (page, sort, etc.). You can provide your own component via the `offline` prop:

```jsx
import { DeletedRecordsList } from '@react-admin/ra-soft-delete';
import { Alert } from '@mui/material';

const offline = <Alert severity="warning">No network. Could not load the posts.</Alert>;

export const CustomDeletedRecords = () => (
<DeletedRecordsList offline={offline} />
);
```

## `pagination`

By default, the `<DeletedRecordsList>` view displays a set of pagination controls at the bottom of the list.
Expand Down
2 changes: 1 addition & 1 deletion docs/SoftDeleteDataProvider.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -185,7 +185,7 @@ export const dataProvider = addSoftDeleteInPlace(

**Note:** When using `addSoftDeleteInPlace`, avoid calling `getListDeleted` without a `resource` filter, as it uses a naive implementation combining multiple `getList` calls, which can lead to bad performance. It is recommended to use one list per resource in this case (see [`<DeletedRecordsList resource>` property](./DeletedRecordsList.md#resource)).

You can also write your own implementation. Feel free to look at these builders source code for inspiration. You can find it under your `node_modules` folder, e.g. at `node_modules/@react-admin/ra-soft-delete/src/dataProvider/addSoftDeleteBasedOnResource.ts`.
You can also write your own implementation. Feel free to look at these builders source code for inspiration. You can find it under your `node_modules` folder, e.g. at `node_modules/@react-admin/ra-core-ee/src/soft-delete/dataProvider/addSoftDeleteBasedOnResource.ts`.

### Query and Mutation Hooks

Expand Down
26 changes: 23 additions & 3 deletions docs_headless/astro.config.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -218,6 +218,7 @@ export default defineConfig({
{
label: 'Realtime',
items: [
enterpriseEntry('<LockStatusBase>'),
enterpriseEntry('usePublish'),
enterpriseEntry('useSubscribe'),
enterpriseEntry('useSubscribeCallback'),
Expand All @@ -234,7 +235,26 @@ export default defineConfig({
enterpriseEntry('useLockOnCall'),
enterpriseEntry('useGetListLive'),
enterpriseEntry('useGetOneLive'),
enterpriseEntry('<LockStatusBase>'),
],
},
{
label: 'Soft Delete',
items: [
enterpriseEntry('SoftDeleteDataProvider', 'Setting up'),
enterpriseEntry('<DeletedRecordsListBase>'),
enterpriseEntry('<ShowDeletedBase>'),
enterpriseEntry('<DeletedRecordRepresentation>'),
enterpriseEntry('addSoftDeleteBasedOnResource'),
enterpriseEntry('addSoftDeleteInPlace'),
enterpriseEntry('useSoftDelete'),
enterpriseEntry('useSoftDeleteMany'),
enterpriseEntry('useGetListDeleted'),
enterpriseEntry('useGetOneDeleted'),
enterpriseEntry('useRestoreOne'),
enterpriseEntry('useRestoreMany'),
enterpriseEntry('useHardDelete'),
enterpriseEntry('useHardDeleteMany'),
enterpriseEntry('useDeletedRecordsListController'),
],
},
{
Expand Down Expand Up @@ -279,10 +299,10 @@ export default defineConfig({
* @param {string} name
* @returns {any}
*/
function enterpriseEntry(name) {
function enterpriseEntry(name, label = name) {
return {
link: `${name.toLowerCase().replace(/</g, '').replace(/>/g, '')}/`,
label: name,
label,
attrs: { class: 'enterprise' },
badge: {
text: 'React Admin Enterprise',
Expand Down
56 changes: 56 additions & 0 deletions docs_headless/src/content/docs/DeletedRecordRepresentation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
---
title: "<DeletedRecordRepresentation>"
---

A component that renders the record representation of a deleted record.

This feature requires a valid [Enterprise Edition](https://marmelab.com/ra-enterprise/) subscription.

## Installation

```bash
npm install --save @react-admin/ra-core-ee
# or
yarn add @react-admin/ra-core-ee
```

## Usage

```tsx
import { CoreAdmin, CustomRoutes, WithRecord } from 'react-admin';
import { Route } from 'react-router-dom';
import { DeletedRecordsListBase, ShowDeletedBase, type DeletedRecordType } from '@react-admin/ra-core-ee';

export const App = () => (
<CoreAdmin>
...
<CustomRoutes>
<Route
path="/deleted"
element={
<DeletedRecordsListBase>
<WithListContext
render={({ isPending, data }) => isPending ? null : (
<ul>
{data.map(record => (
<li key={record.id}>
<div><strong>{record.resource}</strong></div>
<DeletedRecordRepresentation record={record} />
</li>
))}
</ul>
)}
/>
</DeletedRecordsListBase>
}
/>
</CustomRoutes>
</CoreAdmin>
);
```

## Props

| Prop | Required | Type | Default | Description |
|------------|----------|------------|---------|---------------------------------------------------------------------------------------|
| `record` | Optional | `RaRecord` | | The deleted record. If not provided, the record from closest `RecordContext` is used. |
Loading
Loading