Dashboard

How to set up and configure the Dashboard

Dashboard is a tool for Sanity Studio that picks up and renders any widgets which implement part:@sanity/dashboard/widget in your project. A widget is a React component that you can install if it's published on npm under the sanity-plugins- namespace. You can also write your own custom project-specific widgets.

Widgets are useful for displaying stats about your content, list recently edited or stale documents, portraying the daily cat, or whatever sparks joy for those who logs in to the Studio.

The Dashboard tool has been designed to be as generic as possible, making few assumptions about its widgets. The Dashboard itself is mostly concerned about the layout of the configured widgets. The layout and order, as well as the widgets’ configurable options can be set in a simple file.

Installing the Dashboard

If you have started a project from sanity.io/create you probably already have the Dashboard installed. If you wish to install it in existing projects

  1. cd to your project’s Sanity Studio
  2. Type sanity install @sanity/dashboard. This will cause two things happen:
    • The Dashboard tool gets installed to ./node_modules in your Studio
    • @sanity/dashboard is appended to the plugins array in the sanity.json file of your Studio
  3. To verify that all is well, fire up your Studio (sanity start) and point your browser to http://localhost:3333/dashboard

Gotcha

Sometimes you want the Dashboard to be the first thing people see when they log in to the Studio, sometimes the Desk tool. This depends on what comes first in the plugins-array in sanity.json.

How to configure the Dashboard

Chances are that you want to change the default layout. The layout, as well as widgets' configurable options, are controled by a single file that exports a configuration object. Just as you do with the schemas and the structure builder.

Adding your own configuration file

First create a file called dashboardConfig.js inside your project folder. Figure out it's relative path to the project’s root folder, especially if you have chosen another filename, or have added it to a subfolder.

Add this entry to the parts array in your sanity.json file, append the following line to the parts array:

{ 
  "implements": "part:@sanity/dashboard/config", 
  "path": "./dashboardConfig.js" 
}

Your dashboardConfig.js file has to export a ES6 module object. To reproduce the default layout, it would have to look like this:

export default {
  widgets: [
    {
      name: 'sanity-tutorials'
    },
    {
      name: 'project-info'
    },
    {
      name: 'project-users'
    }
  ]
}

The widgets array is how you tell the Dashboard which widgets to render in the order they appear in the array. The ones mentioned in the above example are bundled with Sanity and require no separate installation.

Restart your Studio and play around with the order of the widgets array in src/dashboardConfig.js. You can also duplicate them, should you want multiple instances of the same widget.

The default Dashboard