Dashboard Widgets

The AdminCP dashboard at /admin/core is a grid of widgets. Your plugin can drop its own cards onto it - post counts, a moderation queue, a chart, whatever you want an admin to see the moment they log in.

Every admin arranges their own dashboard: drag to reorder, drag new widgets in from the side panel, resize, remove. One admin rearranging their board never touches anyone else's.

┌─ Edit layout ────────────────────────────────┬─ Available widgets ─┐
│ ┌───────────────┬──────────┐                 │ Search for a widget │
│ │ Notes         │ Send a   │                 │                     │
│ │               │ notifi…  │                 │ CORE                │
│ ├───────────────┴──────────┤                 │ ⠿ Notes             │
│ │ ⌐ ‥ drop a widget here ¬ │                 │ ⠿ Send a notificat… │
│ └──────────────────────────┘                 │ BLOG                │
│                                              │ ⠿ Blog statistics   │
│                                              │                     │
│                                              │  drag one over ───▶ │
│                                              ├─────────────────────┤
│                                              │  Cancel  │   Save   │
└──────────────────────────────────────────────┴─────────────────────┘

Edit layout sits in the page header. Once the board is being edited it steps aside, and Save and Cancel wait at the foot of the widget panel - beside the rest of what edit mode put on screen, rather than back up in the header.

Register a widget

import type { AdminDashboardWidgetProps } from "@vitnode/core/lib/plugin";

export const StatsWidget = async ({ settings }: AdminDashboardWidgetProps) => {
  const posts = await countPosts();

  return (
    <p className="text-3xl font-bold tabular-nums">{posts}</p>
  );
};

import { I18nProvider } from "@vitnode/core/components/i18n-provider";

export const StatsWidget = () => (
  <I18nProvider namespaces={["@vitnode/blog.admin.dashboard"]}>
    <StatsChart />
  </I18nProvider>
);

import { buildPlugin } from "@vitnode/core/lib/plugin";
import { ChartBarIcon } from "lucide-react";

import { StatsWidget } from "./views/admin/widgets/stats-widget";
import { configPlugin } from "./config";

export const blogPlugin = () => {
  return buildPlugin({
    ...configPlugin,
    admin: {
      dashboard: {
        widgets: [
          {
            id: "stats",
            component: StatsWidget,
            icon: <ChartBarIcon />,
            defaultSpan: 1,
            defaultRows: 1,
          },
        ],
      },
    },
  });
};

{
  "@vitnode/blog": {
    "title": "Blog",
    "admin": {
      "dashboard": {
        "widgets": {
          "stats": {
            "title": "Blog statistics",
            "desc": "Posts, comments and views at a glance."
          }
        }
      }
    }
  }
}

Widget options

Grouping widgets in the panel

The panel groups what it offers under headings, and the search box above them matches a widget's title, its description, and its heading - so typing your plugin's name lists everything it contributes.

By default a widget is filed under the plugin it came from, using the same title your plugin already provides for the sidebar. Register three widgets and they arrive as one Blog group, in the order you declared them - nothing to configure.

Give related widgets a category when one heading is too coarse:

widgets: [
  { id: "stats", component: StatsWidget, category: "reports" }, 
  { id: "views", component: ViewsWidget, category: "reports" }, 
  { id: "queue", component: QueueWidget }, // filed under "Blog"
],

The heading's text is a translation of its own, keyed by the category id:

{
  "@vitnode/blog": {
    "admin": {
      "dashboard": {
        "widgets": {
          "categories": {
            "reports": "Blog reports"
          }
        }
      }
    }
  }
}

Letting a widget be placed more than once

Some widgets earn their keep several times over - one card per thing being watched. Set allowMultiple and the widget stays in the panel after it is placed, so an admin can drag in as many copies as they want:

{
  id: "queue",
  component: QueueWidget,
  allowMultiple: true, 
}

Every copy is a layout entry of its own, with its own size, position and settings. They are told apart by id: the first copy keeps the plain widget id, later ones get a #n suffix.

@vitnode/blog:queue      <- first copy
@vitnode/blog:queue#2    <- second
@vitnode/blog:queue#3    <- third

That id arrives as widgetId in your props, and it is what settings are stored against. Pass it back verbatim when you save - never substitute the id you registered, or every copy will write over the same bag:

export const QueueWidget = ({ settings, widgetId }: AdminDashboardWidgetProps) => (
  // `widgetId` is this copy - `@vitnode/blog:queue#2`, say.
  <QueueContent defaultValue={settings.filter} widgetId={widgetId} />
);

Turning allowMultiple back off is safe: the extra copies are dropped on the next load and the first one is kept.

Sizing and responsiveness

span is a column count, not a pixel width, and the grid changes column count with the viewport:

Because the span collapses gracefully, one saved layout serves every screen size - there is no separate mobile layout to keep in sync. Design your widget to look right at span: 1 on a phone and it will look right everywhere.

Gate a widget by permission

Same shape as nav items - see Staff Permissions:

{
  id: "moderation-queue",
  component: ModerationQueueWidget,
  permission: { module: "posts", permission: "can_view" }, 
}

An admin without the permission never sees the widget - not on the board, not in the panel. If they had it placed and the permission is later revoked, it quietly disappears from their layout without disturbing anything else.

Remembering things (widget settings)

Each widget gets a small JSON bag of its own, stored per admin alongside their layout. Core's Notes widget uses it to keep the note body; yours might remember a collapsed section or a chosen date range.

Read it from the settings prop:

export const StatsWidget = ({ settings }: AdminDashboardWidgetProps) => {
  const range = settings.range === "year" ? "year" : "month";
  // ...
};

Write it from a client child with the server action core ships:

"use client";

import { saveWidgetSettingsMutation } from "@vitnode/core/views/admin/views/core/dashboard/widgets/save-widget-settings.server";

export const RangePicker = ({ widgetId }: { widgetId: string }) => (
  <button
    onClick={() =>
      saveWidgetSettingsMutation({ widgetId, settings: { range: "year" } })
    }
  >
    Last year
  </button>
);

Settings are merged, not replaced, so you only send the keys you changed. Rearranging the dashboard never wipes them. The whole bag is capped at 64 KB of UTF-8 - a dashboard is not a CMS.

Let admins configure it (the settings dialog)

Saving straight from the card suits things the admin is already typing into. For everything else - a default message, a date range, which forum to watch - there is a gear in the card's top-right corner while the board is being edited, and a dialog behind it. Register a settingsComponent and VitNode puts it there, next to the sizing and removal buttons:

{
  id: "stats",
  component: StatsWidget,
  settingsComponent: StatsSettings, 
}

import type { AdminDashboardWidgetProps } from "@vitnode/core/lib/plugin";

import { StatsSettingsForm } from "./stats-settings-form";

export const StatsSettings = ({ settings }: AdminDashboardWidgetProps) => (
  <StatsSettingsForm
    defaultRange={settings.range === "year" ? "year" : "month"}
  />
);

"use client";

import { AutoForm } from "@vitnode/core/components/form/auto-form";
import { AutoFormSelect } from "@vitnode/core/components/form/fields/select";
import { useWidgetSettingsDialog } from "@vitnode/core/views/admin/views/core/dashboard/grid/widget-settings-dialog";
import { z } from "zod";

export const StatsSettingsForm = ({
  defaultRange,
}: {
  defaultRange: string;
}) => {
  const { save } = useWidgetSettingsDialog();

  // Whatever this copy has already saved becomes the form's starting value.
  const formSchema = z.object({
    range: z
      .enum(["month", "year"])
      .default(defaultRange === "year" ? "year" : "month"),
  });

  return (
    <AutoForm
      fields={[
        {
          id: "range",
          component: props => <AutoFormSelect label="Range" {...props} />,
        },
      ]}
      formSchema={formSchema}
      mode="all"
      onSubmit={async values => {
        await save({ range: values.range }); 
      }}
      submitButtonProps={{ children: "Save" }}
    />
  );
};

The dialog's own title and description come from the widget's title - you only supply what goes between them and a footer to close it.

Your widget reads the result back out of its settings prop like any other. As soon as the write lands, VitNode renders that one card again on the server and swaps it in behind the closing dialog - your component runs a second time with the settings that were just saved, and remounts, so whatever client state it was holding starts from them too. Its skeleton covers the gap.

Only that card goes back to the server. The board around it is left exactly as the admin arranged it, which is why a full reload waits for them to save or cancel their layout.

How it is stored

An admin's layout lives in core_admin_dashboard, one row per user, as a jsonb array of { id, span, rows, settings } in render order. It is a preference, never the source of truth: on every load VitNode reconciles it against what is actually installed, so uninstalling your plugin simply drops its widgets from everyone's board, and installing it adds any defaultEnabled widgets to the end without disturbing what the admin already arranged.

Removing a widget does not delete its entry - it is kept as { hidden: true }. That does two useful things: a defaultEnabled widget the admin threw away stays away instead of cheerfully reappearing on the next load, and its settings sit safely on ice until they put it back.

Only what the admin could actually see counts as removed. An entry they were never shown - your plugin was uninstalled, or a permission behind one of its widgets was revoked - is left untouched by a save rather than quietly marked hidden, so putting the plugin or the permission back brings the card back exactly where it was, settings and all.

Learn More