Dashboard Widgets

The Dashboard is the first page users see when they log into the Payload Admin Panel. By default, it displays cards with the collections and globals. You can customize the dashboard by adding widgets - modular components that can display data, analytics, or any other content.

One of the coolest things about widgets is that each plugin can define its own. Some examples:

Analytics
Error Reporting
Number of documents that meet a certain filter
Jobs recently executed

Defining Widgets

Define widgets in your Payload config using the admin.dashboard.widgets property:

1import { buildConfig } from 'payload'
2
3export default buildConfig({
admin: {
  dashboard: {
    widgets: [
      {
        slug: 'sales-summary',
        Component: './components/SalesSummary.tsx#default',
        fields: [
          { name: 'title', type: 'text' },
          {
            name: 'timeframe',
            type: 'select',
            options: ['daily', 'weekly', 'monthly', 'yearly'],
          },
          { name: 'showTrend', type: 'checkbox' },
        ],
        minWidth: 'small',
        maxWidth: 'medium',
      },
    ],
  },
},
25})

Property	Type	Description
`slug` *	`string`	Unique identifier for the widget
`Component` *	`string`	Path to the widget component (supports `#` syntax for named exports)
`fields`	`Field[]`	Optional widget-specific form fields shown in the edit drawer
`minWidth`	`WidgetWidth`	Minimum width the widget can be resized to (default: `'x-small'`)
`maxWidth`	`WidgetWidth`	Maximum width the widget can be resized to (default: `'full'`)

Widgets are React Server Components that receive WidgetServerProps:

1import type { WidgetServerProps } from 'payload'
2
3export default async function UserStatsWidget({ req }: WidgetServerProps) {
const { payload } = req
5
// Fetch data server-side
const userCount = await payload.count({
  collection: 'users',
  overrideAccess: false,
  req,
})
12
return (
  <div className="card">
    <h3>Total Users</h3>
    <p style={{ fontSize: '32px', fontWeight: 'bold' }}>
      {userCount.totalDocs}
    </p>
  </div>
)
21}

For visual consistency with the Payload UI, we recommend:

Use the card class for card-style widget roots. It applies the same theme-aware surface, border, radius, and padding as Payload's built-in dashboard cards; omit it for unframed content.
Use our theme variables for backgrounds and text colors. For example, use var(--color-bg) for backgrounds and var(--color-text) for text colors.

Default Layout

Control the initial dashboard layout with the defaultLayout property:

1export default buildConfig({
admin: {
  dashboard: {
    defaultLayout: ({ req }) => {
      // Customize layout based on user role or other factors
      const isAdmin = req.user?.roles?.includes('admin')
7
      return [
        { widgetSlug: 'collections', width: 'full' },
        {
          widgetSlug: 'sales-summary',
          data: {
            timeframe: 'monthly',
            title: 'Revenue Overview',
          },
          width: isAdmin ? 'medium' : 'small',
        },
        { widgetSlug: 'user-stats', width: isAdmin ? 'medium' : 'full' },
        { widgetSlug: 'revenue-chart', width: 'full' },
      ]
    },
    widgets: [
      // ... widget definitions
    ],
  },
},
27})

The defaultLayout function receives the request object and should return an array of WidgetInstance objects.

If your widget has fields, you can type widgetData with generated widget types:

1import type { WidgetServerProps } from 'payload'
2
3import type { SalesSummaryWidget } from '../payload-types'
4
5export default async function SalesSummaryWidgetComponent({
6  widgetData,
7}: WidgetServerProps<SalesSummaryWidget>) {
8  const title = widgetData?.title ?? 'Sales Summary'
9  const timeframe = widgetData?.timeframe ?? 'monthly'
10
11  return (
12    <div className="card">
13      <h3>
14        {title} ({timeframe})
15      </h3>
16    </div>
17  )
18}

WidgetInstance Type

Property	Type	Description
`widgetSlug` *	`string`	Slug of the widget to display
`data`	`object`	Optional widget-specific data passed to `widgetData`
`width`	`WidgetWidth`	Initial width of the widget (default: minWidth)

width is constrained by each widget's minWidth and maxWidth when types are generated.

Built-in Widgets

Payload includes built-in welcome, activity, collections, and collection-query widgets. The activity widget has Recently Viewed and Pinned tabs. It loads the visible page on demand and displays a single grid row, with up to four documents per page. Its collection filter applies only to Recently Viewed. The collections widget displays collection and global cards. The collection-query widget displays documents from a selected collection.

If you don't define a defaultLayout, welcome, activity, and collections appear in that order, each at full width. The collection-query widget is available through the Add + menu.

User Customization

Users can customize their dashboard by:

Clicking the dashboard dropdown in the breadcrumb
Selecting "Edit Dashboard"
Adding widgets via the "Add +" button
Editing widget data (for widgets with fields) via the edit button
Resizing widgets using the width dropdown on each widget (if multiple widths are allowed)
Reordering widgets via drag-and-drop
Deleting widgets using the delete button
Saving changes or canceling to revert

Users can also reset their dashboard to the default layout using the "Reset Layout" option.

Was this page helpful?

See what others are building with Payload.

"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."

Get the resources you need to start building today

Microsoft chose Payload to tell the world about AI.

Dashboard Widgets

Defining Widgets

Widget Configuration

Creating a Widget Component

Default Layout

WidgetInstance Type

Built-in Widgets

User Customization

Document Views