@materialui-reactjs/admin

A React component and utility library for building modern admin applications, including admin dashboards, CRUD interfaces, data tables, forms, charts, navigation, and reusable layouts.

The package provides multiple subpath exports so applications can import only the feature groups they need. It is designed to provide a consistent and reusable architecture for React-based admin systems.

Features

• Reusable admin dashboard components
• CRUD components for list, detail, update, and import workflows
• Form components for common and advanced input scenarios
• File and image upload components
• Data tables, pagination, search, tabs, and modal components
• Sidebar and top navigation components
• ECharts-based chart components
• Loading and spinner components
• API and data-handling helpers
• Environment configuration utilities
• Routing and validation helpers
• Drag-and-drop and sortable components
• CKEditor integration
• React Select integration
• MUI Date and Time Picker integration
• Redux Toolkit integration
• Bootstrap and MUI based UI components

Package Structure

The package exposes different feature groups through subpath exports:

| Import Path | Description | | -------------------------------------- | -------------------------------------------------------------------------- | | @materialui-reactjs/admin | Main exports for commonly used components | | @materialui-reactjs/admin/form | Form fields, form builders, and upload components | | @materialui-reactjs/admin/hook | Hooks and helpers for list, detail, update, and import workflows | | @materialui-reactjs/admin/utils | API, routing, environment, validation, and utility helpers | | @materialui-reactjs/admin/meta | Tables, tabs, pagination, modals, headers, search, and other UI components | | @materialui-reactjs/admin/sidebar | Sidebar navigation | | @materialui-reactjs/admin/single | Single-resource CRUD components | | @materialui-reactjs/admin/top-navbar | Top navigation | | @materialui-reactjs/admin/echarts | ECharts components | | @materialui-reactjs/admin/loader | Loading and spinner components |

Main Components

Form Components

The form package provides reusable components for building complex admin forms.

• AdvancedMultiSelect
• AsxhUImages
• BoxAddRow
• CheckTreeBox
• CusForm
• DateInput
• DateTimeInput
• Editor
• EfFile
• EfImage
• EfImages
• PImage
• SelectAddRowBox
• SelectAddRowBoxAdvanced
• SelectBox
• UDragFile
• UFile
• UFiles
• UImages

These components support:

• Standard form inputs
• Select and multi-select fields
• Tree-based selection
• Date and time inputs
• Rich text editing
• File uploads
• Image uploads
• Dynamic form rows
• Drag-and-drop file handling

Meta UI Components

The meta package contains reusable UI components for admin pages.

• BtnGroup
• CardTable
• CusTooltip
• ElfinderModal
• Error403
• Error404
• Head
• HeaderDetail
• HeaderIndex
• HeaderUpdate
• ModalForm
• Navtabs
• Pagination
• PDFEmbed
• ScrollTable
• SearchBox
• SortableItem

These components can be used to build:

• Index pages
• Detail pages
• Update pages
• Data tables
• Search interfaces
• Pagination
• Navigation tabs
• Modal forms
• Page headers
• Error pages
• Scrollable tables

Single-Page CRUD Components

The single package provides reusable components for building CRUD pages around a single resource.

• List
• Detail
• Update
• UpdateDetail
• UpdateTableDetail
• Import
• Fields

A typical resource can be structured as:

Resource
├── List
├── Detail
├── Update
└── Import

This structure is useful for applications that use a consistent CRUD architecture across multiple resources.

Layout Components

Sidebar

The sidebar package provides navigation components for admin dashboards.

import { Sidebar } from "@materialui-reactjs/admin/sidebar";

It also exports:

• MenuItem
• SidebarProps

Top Navbar

The top navigation component provides the main navigation header for an admin application.

import { TopNavbar } from "@materialui-reactjs/admin/top-navbar";

ECharts Components

The echarts package provides reusable chart components based on ECharts.

• BarChart
• LineChart
• MultiBarChart
• MultiLineChart
• PieChart

Example:

import { BarChart } from "@materialui-reactjs/admin/echarts";

export default function DashboardChart() {
    return <BarChart />;
}

Loader

The loader package provides loading indicators.

• SpinnerLoader

Example:

import { SpinnerLoader } from "@materialui-reactjs/admin/loader";

export default function Loading() {
    return <SpinnerLoader />;
}

Hooks

The hook package provides reusable helpers for common admin data workflows.

Available helpers include:

• fetchHookData
• handleHookClickPage
• handleHookSeachForm
• handleHookChange
• convertQueryToSort
• convertSortToQuery

These helpers can be used to standardize:

• API data loading
• Pagination
• Search
• Sorting
• Form changes
• List/detail/update workflows

Example:

import {
    fetchHookData,
    handleHookClickPage,
    handleHookChange,
} from "@materialui-reactjs/admin/hook";

Utilities

The utils package provides common utilities for admin applications.

Available utilities include:

• callFetchApi
• callFetchApiToken
• createQueryString
• loadEnv
• getEnv
• reloadEnv
• escapeHtml
• CusRoute

Example:

import {
    callFetchApi,
    callFetchApiToken,
    createQueryString,
} from "@materialui-reactjs/admin/utils";

Installation

Install the package using npm:

npm install @materialui-reactjs/admin

Or using yarn:

yarn add @materialui-reactjs/admin

Or using pnpm:

pnpm add @materialui-reactjs/admin

Runtime configuration (/env.json)

The package reads its runtime configuration from /env.json served at the app root. Recognised keys: API_URL, ADMIN_URI, UPLOADS_URL, STATIC_URL, SECRET_KEY.

{
    "API_URL": "https://example.com/api",
    "ADMIN_URI": "/admin",
    "UPLOADS_URL": "https://example.com/uploads",
    "STATIC_URL": "https://example.com/static",
    "SECRET_KEY": "..."
}

Notes:

• The file is fetched once, in the background — it never blocks the module graph, and a missing or invalid env.json is not fatal. Values simply resolve to "".
• Read values at any time with getEnv(), and force a retry with reloadEnv().
• SECRET_KEY is sent as the Secret-Key request header. It is visible to the browser — never put a real privileged credential here; treat it as a shared public identifier only.

jQuery

Form validation (Validator) requires jQuery, declared as a peer dependency. Load it before rendering any form component:

import "jquery";

If jQuery is missing, the error thrown points at this requirement instead of failing silently during import.

Basic Usage

Components can be imported directly from their corresponding subpath.

import { Sidebar } from "@materialui-reactjs/admin/sidebar";
import { TopNavbar } from "@materialui-reactjs/admin/top-navbar";
import { CardTable } from "@materialui-reactjs/admin/meta";
import { CusForm } from "@materialui-reactjs/admin/form";

export default function AdminLayout() {
    return (
        <>
            <TopNavbar />
            <Sidebar />
            <CardTable />
            <CusForm />
        </>
    );
}

Import by Feature Group

Form

import { CusForm, DateInput, DateTimeInput, SelectBox } from "@materialui-reactjs/admin/form";

Meta

import { CardTable, Pagination, SearchBox, ModalForm } from "@materialui-reactjs/admin/meta";

Sidebar

import { Sidebar } from "@materialui-reactjs/admin/sidebar";

Top Navbar

import { TopNavbar } from "@materialui-reactjs/admin/top-navbar";

ECharts

import { BarChart, LineChart, PieChart } from "@materialui-reactjs/admin/echarts";

Loader

import { SpinnerLoader } from "@materialui-reactjs/admin/loader";

Utilities

import {
    callFetchApi,
    callFetchApiToken,
    loadEnv,
    getEnv,
    reloadEnv,
} from "@materialui-reactjs/admin/utils";

Styles and CSS

Changed in 2.0.0. The main entry no longer auto-imports the stylesheet. Import it explicitly, as shown below. See CHANGELOG.md for the migration note.

The package provides CSS files for its components.

Import the main stylesheet:

import "@materialui-reactjs/admin/style.css";

If you use Font Awesome Pro (shipped with this package), import it too:

import "@materialui-reactjs/admin/fontawesome.css";

Why the explicit import: the main stylesheet is ~1.4 MB (material-dashboard, jQuery UI, elFinder, icon fonts). Bundling it into the main entry forced every consumer to download all of it even when using a single component.

Some component groups import their own small internal CSS automatically — that is fine.

Make sure your application's build configuration supports CSS imports from npm packages.

Module formats

Both ESM and CommonJS builds are published.

| Format | Entry | Resolved by | | ------ | --------------- | ----------------------------------------------------------- | | ESM | dist/**/*.js | import (bundlers, Vite, webpack, Node ESM) | | CJS | dist/**/*.cjs | require (Jest's default resolver, webpack 4, legacy Node) |

// ESM
import { CardTable } from "@materialui-reactjs/admin";

// CommonJS
const { CardTable } = require("@materialui-reactjs/admin");

Note: this is a browser library. Several components import bootstrap at module scope, which touches document on load. Under require() you therefore still need a DOM environment (e.g. Jest's jsdom test environment, or a bundler targeting browsers).

Dependencies

This package is built with and integrates with the following libraries.

UI and Styling

| Package | Purpose | | --------------------- | --------------------------------------------- | | @mui/material | Material UI components and UI system | | @mui/x-date-pickers | Date and time picker components for MUI | | @emotion/react | Emotion styling engine | | @emotion/styled | Styled components powered by Emotion | | bootstrap | CSS framework and responsive layout utilities |

React and State Management

| Package | Purpose | | -------------------- | ------------------------------- | | react | Core React library | | react-dom | React DOM rendering | | @reduxjs/toolkit | Redux state management | | react-redux | React bindings for Redux | | react-router-dom | Client-side routing | | react-helmet-async | Managing document head metadata |

Form and Editor

| Package | Purpose | | --------------------------- | ---------------------------------- | | @ckeditor/ckeditor5-react | CKEditor React integration | | react-select | Select and multi-select components | | date-fns | Date manipulation and formatting | | decimal.js | Precise decimal calculations |

Drag and Drop / Sorting

| Package | Purpose | | -------------------- | ------------------------------------ | | @dnd-kit/sortable | Sortable drag-and-drop functionality | | @dnd-kit/utilities | Utilities for dnd-kit | | @hello-pangea/dnd | Drag-and-drop components for React | | react-sortablejs | React integration for SortableJS | | sortablejs | Drag-and-drop sorting engine |

Charts

| Package | Purpose | | ------------------- | -------------------------------------- | | echarts | Charting and data visualization engine | | echarts-for-react | React wrapper for ECharts |

Utilities and Notifications

| Package | Purpose | | --------------------------- | ---------------------------------------------------- | | jquery | DOM manipulation and third-party library integration | | sweetalert2 | Alerts, confirmations, and notifications | | sweetalert2-react-content | React integration for SweetAlert2 |

Testing

Unit tests use Vitest with React Testing Library. Test sources live in test/ and are kept out of the published package (files only ships dist).

| Command | Purpose | | ----------------------- | ----------------------------------------- | | npm test | Run the suite once | | npm run test:watch | Watch mode | | npm run test:coverage | V8 coverage report | | npm run typecheck | tsc for both src and test | | npm run lint | ESLint (flat config) | | npm run format | Prettier write | | npm run format:check | Prettier check — gated in verify/CI | | npm run verify | format:check → lint → typecheck → test |

verify and CI both run format:check first, so code that drifts from the Prettier config fails fast instead of accumulating as unreviewed diff noise.

ckeditor5 is declared as an optional peer dependency: it is only needed if you use the Editor component. The editor build (src/ckeditor/) is plain TypeScript that imports from ckeditor5, so CKEditor is never bundled into this package — the consumer installs it and their bundler tree-shakes it, so an app only ever ships a single copy of CKEditor.

npm test              # run once
npm run test:watch    # watch mode
npm run test:coverage # + coverage report (./coverage)
npm run typecheck     # tsc for src and test

Coverage config lives in vitest.config.ts (kept separate from vite.config.ts so the library build is never affected by test settings). The suite focuses on the behaviour that is easy to regress silently:

| Area | What is locked down | | ------------------------------- | ------------------------------------------------------------------------------------------------ | | checkUploadFile | rejects (never hangs) on bad extension, oversize, empty list; honours a custom RegExp | | checkPermission | fail-closed, recurses into subs, respects status, groupId guards | | escapeHtml / showMessage | escapes all 5 HTML metacharacters, type allowlist, { raw: true } opt-in | | getIdParams | edit/detail routes, trailing segments, nested routes, custom pattern | | Env | 404 and network errors resolve to {} instead of rejecting; single fetch; reloadEnv() | | Validator | resolves jQuery lazily; clear error when jQuery is missing | | Upload components | object URLs are cached, revoked on remove and on unmount, and never recreated on re-render | | CardTable | raw API data is never injected as HTML (selecthtml without func) | | SpinnerLoader | children still render when loading is undefined | | SingleIndex | 403 on missing permission, page from the query string, pagination re-fetches, DELETE on delete | | SearchBox | reads filter[field] dynamically so inputs reflect the active filter | | RatioKeyVal | radio ids are unique and stable across re-renders (useId, not Math.random) | | File hooks | an empty FileList yields null, not undefined, so the key survives JSON | | deepMerge / handleObjChange | nested {a}{b} field names rebuild the object; deepMerge does not mutate its inputs | | Sidebar | menus are filtered by module/status/isPer; active state tracks currentPath | | ECharts wrappers | each series entry becomes its own series; visible triggers resize() |

Test helpers live in test/helpers/:

• makeFile(name, { size }) — a File with a controllable size
• makeFileList(files) — a FileList (jsdom has no constructor for it)
• withTimeout(promise) — fails loudly if a promise never settles

Requirements

The package is designed for modern React applications.

Current core versions include:

• React 19.3.x
• React DOM 19.3.x
• React Router 7.x
• MUI 9.x
• MUI X Date Pickers 9.x
• Redux Toolkit 2.x
• Bootstrap 5.x
• ECharts 6.x

For the exact versions used by a particular release, check the package's package.json.

Node >=20.19.0 is required (Vite 8's floor for consumers). CI runs on Node 24 because the dev-only jsdom@30 needs a newer runtime.

License

MIT — see LICENSE.

Changelog

See CHANGELOG.md. The 2.4.0 release fixes three packaging bugs found by installing the packed tarball into a clean project, and adds a consumer smoke test to CI to prevent regressions of that kind. 2.3.0 adds tests for the form components; 2.2.0 was a type-safety pass over the public API; 2.1.1 fixed a 27.7 MB stylesheet caused by inlined webfonts; 2.1.0 was a test-coverage pass, and 2.0.0 contained the breaking change where the main stylesheet is no longer auto-imported.