Installing and configuring widgets

How to install and configure widgets for Dashboard

Installing widgets

You install Dashboard widgets as you would any other Sanity Studio plugin.

For example, if you want to install the cats example widget mentioned below, proceed as follows:

  1. Type sanity install dashboard-widget-cats in your terminal inside your project folder (this works because it's published on npm under the name sanity-plugin-dashboard-widget-cats).
  2. Update your src/dashboardConfig.js file by adding {name: 'cats'} to the widgets array.
  3. You've now got a cat in your Studio.

Changing layout

A widget’s size can be defined by adding a layout key to the widget entry:

// dashboardConfig.js
export default {
  widgets: [
    {
      name: 'sanity-tutorials'
    },
    {
      name: 'project-info',
      layout: {
        width: 'large',
        height: 'small'
      }
    },
    {
      name: 'project-users',
      layout: {
        width: 'medium',
        height: 'small'
      }
    }
  ]
}

The accepted values for width and height are:

  • auto
  • small
  • medium
  • large
  • full
Some layout examples

Configuring widget options

Some widgets allow options to change aspects of their behavior. The configuration options should be part of the widget’s documentation found in its README.md. If you install the document-list widget (sanity install dashboard-widget-document-list), it can be configured with:

// dashboardConfig.js
export default {
  widgets: [
    {
      name: 'document-list', 
      options: {
        title: 'Last edited posts', 
        order: '_updatedAt desc', 
        types: ['post']
      }
    }
  ]
}

Thus, if you want your dashboard to display both newest documents across all document types and another widget showing the last edited posts, your dashboardConfig.js would look like this:

// dashboardConfig.js
export default {
  widgets: [
    {
      name: 'document-list',
      options: {
        title: 'Last edited documents',
        order: '_updatedAt desc',
      },
      layout: {
        width: 'auto',
        height: 'large'
      }
    },
    {
      name: 'document-list',
      options: {
        title: 'Last edited posts',
        order: '_updatedAt desc',
        types: ['post']
      }
    }
  ]
}
Document lists with configuration