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) {
4  const { payload } = req
5
6  // Fetch data server-side
7  const userCount = await payload.count({ collection: 'users' })
8
9  return (
10    <div className="card">
11      <h3>Total Users</h3>
12      <p style={{ fontSize: '32px', fontWeight: 'bold' }}>
13        {userCount.totalDocs}
14      </p>
15    </div>
16  )
17}

For visual consistency with the Payload UI, we recommend:

Using the card class for your root element, unless you don't want it to have a background color.
Using our theme variables for backgrounds and text colors. For example, use var(--theme-elevation-0) for backgrounds and var(--theme-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 a built-in collections widget that displays collection and global cards.

If you don't define a defaultLayout, the collections widget will be automatically included in your dashboard.

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.

Document Views

Dashboard Widgets

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) {
4  const { payload } = req
5
6  // Fetch data server-side
7  const userCount = await payload.count({ collection: 'users' })
8
9  return (
10    <div className="card">
11      <h3>Total Users</h3>
12      <p style={{ fontSize: '32px', fontWeight: 'bold' }}>
13        {userCount.totalDocs}
14      </p>
15    </div>
16  )
17}

For visual consistency with the Payload UI, we recommend:

Using the card class for your root element, unless you don't want it to have a background color.
Using our theme variables for backgrounds and text colors. For example, use var(--theme-elevation-0) for backgrounds and var(--theme-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 a built-in collections widget that displays collection and global cards.

If you don't define a defaultLayout, the collections widget will be automatically included in your dashboard.

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.

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

Dashboard Widgets

Defining Widgets

Widget Configuration

Creating a Widget Component

Default Layout

WidgetInstance Type

Built-in Widgets

User Customization