Universal React Dashboard

An accessible, responsive, and themeable dashboard component library for React applications. It ships ESM, CommonJS, TypeScript declarations, source maps, and one extracted CSS file.

Included

• Responsive DashboardShell, Sidebar, TopBar, PageHeader, and grid layout
• Light, dark, and system themes with typed token overrides
• Buttons, badges, avatars, cards, stat cards, progress bars, tables, skeletons, and empty states
• React 18 and React 19 peer support
• Rollup library build, strict TypeScript, ESLint, Vitest, and coverage thresholds
• Runnable Vite example and npm publishing workflow

Project structure

src/
├── components/
│   ├── data/          # DataTable, ProgressBar, StatCard
│   ├── feedback/      # EmptyState, Skeleton
│   ├── layout/        # DashboardShell, Sidebar, TopBar, PageHeader, Grid
│   └── primitives/    # Avatar, Badge, Button, Card, IconButton
├── styles/            # Scoped component and token styles
├── theme/             # Provider, context, defaults, theme factory
├── test/              # Shared test setup
├── index.ts           # Public package API
└── types.ts           # Public theme and navigation types
examples/basic/        # Runnable consumer application
rollup.config.mjs      # ESM, CJS, CSS, declarations, minification

Local development

Requirements: Node.js 20 or newer and npm 10 or newer.

npm install
npm run validate
npm run example

The final command builds the library and starts the example application. During component development, run npm run build:watch in one terminal and npm run dev --workspace @atfatanpmjs/react-dashboard-example in another.

Consumer installation

npm install @atfatanpmjs/react-dashboard

Import the stylesheet once near the application entry point:

import "@atfatanpmjs/react-dashboard/styles.css";

Then compose a dashboard:

import {
  Avatar,
  Button,
  DashboardGrid,
  DashboardShell,
  DashboardThemeProvider,
  PageHeader,
  StatCard,
  useDashboardTheme,
  type NavigationItem,
} from "@atfatanpmjs/react-dashboard";

const navigation: NavigationItem[] = [
  { id: "home", label: "Overview", href: "/", active: true },
  { id: "users", label: "Customers", href: "/customers" },
];

function ThemeButton() {
  const { resolvedMode, toggleMode } = useDashboardTheme();
  return (
    <Button onClick={toggleMode} variant="secondary">
      Use {resolvedMode === "dark" ? "light" : "dark"} mode
    </Button>
  );
}

export function App() {
  return (
    <DashboardThemeProvider persistKey="app-theme">
      <DashboardShell
        brand="atfatanpmjs"
        navigation={navigation}
        headerActions={
          <>
            <ThemeButton />
            <Avatar alt="Ada Lovelace" initials="AL" />
          </>
        }
      >
        <PageHeader title="Overview" actions={<Button>New report</Button>} />
        <DashboardGrid>
          <StatCard label="Revenue" value="€28,400" />
          <StatCard label="Customers" value="1,482" />
        </DashboardGrid>
      </DashboardShell>
    </DashboardThemeProvider>
  );
}

For client-side routers, omit href and provide onSelect, or handle every item through DashboardShell.onNavigate.

Theming

The provider scopes tokens to its wrapper, so multiple dashboard themes can coexist without mutating the document root.

import {
  DashboardThemeProvider,
  createDashboardTheme,
} from "@atfatanpmjs/react-dashboard";

const theme = createDashboardTheme({
  light: {
    colorBrand: "#0f766e",
    colorBrandHover: "#115e59",
    radiusLarge: "1.25rem",
  },
  dark: {
    colorBrand: "#5eead4",
    colorBrandHover: "#99f6e4",
  },
});

<DashboardThemeProvider defaultMode="system" theme={theme}>
  <App />
</DashboardThemeProvider>;

The provider can be controlled using mode and onModeChange, or uncontrolled using defaultMode. Set persistKey only when local preference persistence is wanted.

Build output

npm run build produces:

dist/index.js       # ESM
dist/index.cjs      # CommonJS
dist/index.d.ts     # Bundled declarations
dist/styles.css     # Minified stylesheet
dist/*.map          # Source maps

React and React DOM remain external peer dependencies. Package exports prevent consumers from importing private implementation files, while sideEffects preserves the CSS asset during tree shaking.

Publishing

1. Replace @atfatanpmjs/react-dashboard in the root and example package.json files with your available npm scope and package name.
2. Replace the author/license placeholders and add repository, homepage, and bugs metadata.
3. Commit the generated package-lock.json, then run npm run validate.
4. Inspect the package using npm pack --dry-run and update the version with npm version patch, minor, or major.
5. Sign in with npm login, confirm with npm whoami, then publish using npm publish --access public.

For automated releases, configure npm Trusted Publishing for the repository and keep .github/workflows/publish.yml. It validates every release and publishes with npm provenance. If you use a private registry, update publishConfig, the workflow registry URL, and its authentication method.

Release checklist

• Public API changes are exported only through src/index.ts.
• New components include keyboard behavior, labels, focus states, and reduced-motion handling.
• npm run validate passes.
• The example builds against the packaged public API.
• The version and changelog follow semantic versioning.

License

MIT. Replace the placeholder copyright holder before publishing.