ding-react-admin

Composable admin shell for React apps: Ant Design 6 layout, CRUD field system (lists, forms, filters, inlines, bulk actions), theme/density controls, AuthProvider + useAuth, data / permissions providers (react-admin–style naming, intentionally small), and React Router helpers.

-> Live demo

-> Tutorial

Build an admin app and add a Users page — step-by-step from yarn create vite through CRUD and routes.

Interactive demo on GitHub Pages — sign in with admin / admin or user / user.

Installation

Install ding-react-admin plus its peer dependencies in one command — versions depend on whether you already have React. See docs/install.md (yarn and npm, new vs existing app).

Quick start

Wrap your app with AuthProvider, then render AdminApp with navigation and routes:

import { AdminApp, AuthProvider, createSessionStorageAuthAdapter } from "ding-react-admin";

const navItems = [{ key: "home", label: "Home", path: "/" }];
const routes = [{ path: "/", element: <div>Welcome</div> }];

export function App() {
  return (
    <AuthProvider adapter={createSessionStorageAuthAdapter()}>
      <AdminApp navItems={navItems} routes={routes} />
    </AuthProvider>
  );
}

For CRUD pages, add DataProvider and PermissionsProvider — see Getting started and docs/quick-start.md.

Features

• Declarative CRUD — describe list and form pages in JSX; field source names map to your API
• List tables with column sorting, pagination, and URL-synced query state
• Filters — text, number, boolean, date, select, and reference lookups on list pages
• Page forms and modal forms (ResourceForm, ResourceFormModal) with shared create/edit logic
• Tabbed forms (FormTabs) and stepped forms (FormSteps) for long or wizard-style records
• Reference / lookup fields with inline create and edit actions in a modal
• Inline nested rows — tabular (InlineFormSet) and stacked layouts for related records
• Bulk actions — Django-style row selection and batch operations
• Built-in fields — text, number, boolean, date, select, password, image, file, reference, reference-many
• Permissions — gate list/form actions and nav items per resource (useCan, usePermissions)
• Auth & routing — AuthProvider, login page, Protected / GuestOnly route guards
• Theme & density — light/dark mode and compact/comfortable layout switches
• Validation errors — map API responses to field errors (Django REST, .NET, Node helpers included)
• Data layer — DataProvider contract plus REST and in-memory handler factories
• Uploads — image/file fields with FormData submit support

Screenshots

From the playground demo:

List with filters

Tabbed form page

Stepped modal form

Login

Declarative CRUD

Wire a DataProvider (see Providers below), then describe list and form pages in JSX — field source names map to your API. Filters, modals, permissions, and validation plug in when you need them; start with the basics:

List page

import { ResourceList, TextColumn, DateColumn } from "ding-react-admin";

export function InvoiceListPage() {
  return (
    <ResourceList resource="invoices" title="Invoices" pathPrefix="/invoices">
      <TextColumn source="number" label="Number" />
      <TextColumn source="customer" label="Customer" />
      <DateColumn source="issuedAt" label="Issued" />
    </ResourceList>
  );
}

Add <TextFilter />, <ReferenceFilter />, bulk actions, and row permissions inside the same component — list pages guide.

Form page

import { ResourceForm, TextField, DateField } from "ding-react-admin";

export function InvoiceFormPage() {
  return (
    <ResourceForm resource="invoices" title="Invoice" listPath="/invoices">
      <TextField source="number" label="Number" required />
      <TextField source="customer" label="Customer" required />
      <DateField source="issuedAt" label="Issued" required />
    </ResourceForm>
  );
}

Tabbed forms, stepped modals, and API validation errors under fields (fetch, axios, OpenAPI) — forms guide · validation errors.

Inline nested rows

Django-style tabular inlines: related rows edit in a table inside the parent form.

import {
  InlineFormSet,
  NumberField,
  ResourceForm,
  TextField,
} from "ding-react-admin";

<ResourceForm resource="invoices" title="Invoice" listPath="/invoices">
  <TextField source="number" label="Number" required />
  <TextField source="customer" label="Customer" required />
  <InlineFormSet
    field="lines"
    label="Lines"
    columns={[
      {
        source: "label",
        label: "Label",
        cell: ({ name }) => (
          <TextField source="label" name={name} hideLabel required />
        ),
      },
      {
        source: "quantity",
        label: "Qty",
        width: 120,
        cell: ({ name }) => (
          <NumberField source="quantity" name={name} hideLabel required min={0} />
        ),
      },
      {
        source: "unitPrice",
        label: "Unit price",
        cell: ({ name }) => (
          <NumberField
            source="unitPrice"
            name={name}
            hideLabel
            required
            min={0}
            step={0.01}
          />
        ),
      },
    ]}
  />
</ResourceForm>

If you already use react-hook-form, you can pick this up in minutes — nested inlines are just useFieldArray on the same record. See inlines guide.

Providers (manual composition)

Nothing is wired automatically except theme inside <AdminApp />. Wrap providers yourself:

| Provider | Required for | |----------|----------------| | AuthProvider | Login, logout, route guards (Protected, GuestOnly), useAuth | | DataProvider | CRUD components (ResourceList, ResourceForm, …) | | PermissionsProvider | Permission gating in CRUD (usePermissions, useCan) |

Auth only (custom pages, no CRUD yet):

<AuthProvider adapter={createSessionStorageAuthAdapter()}>
  <AdminApp navItems={nav} routes={routes} />
</AuthProvider>

Full stack (CRUD + permissions) — see docs/data-permissions.md and examples/playground/src/main.tsx:

<AuthProvider adapter={authAdapter}>
  <DataProvider value={dataProvider}>
    <PermissionsProvider can={permissions}>
      <AdminApp navItems={nav} routes={routes} />
    </PermissionsProvider>
  </DataProvider>
</AuthProvider>

Use createSessionStorageAuthAdapter for demos; replace with an adapter that calls your API in production. Implement AuthAdapter.login with a LoginCredentials object (username, password, plus any extra fields your login form needs, e.g. businessId). Optionally implement getUserLabel so the account menu shows the logged-in user — see data-permissions.md.

Getting started

New to CRUD: docs/tutorial-one-entity.md — full walkthrough from yarn create vite through Users list/form, data-provider.ts, and routes.

Quick path: docs/quick-start.md — <AuthProvider> + <AdminApp /> with declarative routes.

Full control: docs/composition.md and the playground — your own createBrowserRouter with AdminLayout, Protected, GuestOnly, DataProvider, and PermissionsProvider.

Documentation

| Topic | Guide | |-------|--------| | Install & peer deps | docs/install.md | | Tutorial: add one CRUD entity | docs/tutorial-one-entity.md | | Example playground app | docs/example-app.md | | Sidebar navigation | docs/navigation.md | | CRUD overview | docs/crud/overview.md | | List pages & filters | docs/crud/list-pages.md | | Bulk actions (Django-style) | docs/crud/bulk-actions.md | | Form pages | docs/crud/forms.md | | Reference / lookup fields | docs/crud/references.md | | Inline nested forms | docs/crud/inlines.md | | Custom field types | docs/crud/custom-fields.md | | Data layer & permissions | docs/data-permissions.md | | Form validation errors | docs/form-validation-errors.md | | Routing & auth guards | docs/routing.md | | Login / register layout | docs/auth-pages.md | | Quick start (<AdminApp />) | docs/quick-start.md | | Composition (your own router) | docs/composition.md | | Odoo-style app hub | docs/app-hub.md | | createAdminRouter shortcut | docs/admin-router.md | | Developing next to your app (Vite) | docs/developing.md |

License

MIT