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

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

WidgetWidth Values: 'x-small' \| 'small' \| 'medium' \| 'large' \| 'x-large' \| 'full'

Widgets are React Server Components that receive WidgetServerProps:

For visual consistency with the Payload UI, we recommend:

1. Using the card class for your root element, unless you don't want it to have a background color.
2. 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.

Control the initial dashboard layout with the defaultLayout property:

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

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.

{/* TODO: maybe a good GIF here? */}

Users can customize their dashboard by:

1. Clicking the dashboard dropdown in the breadcrumb
2. Selecting "Edit Dashboard"
3. Adding widgets via the "Add +" button
4. Resizing widgets using the width dropdown on each widget
5. Reordering widgets via drag-and-drop
6. Deleting widgets using the delete button
7. Saving changes or canceling to revert

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