Creating your own widget

Widgets are Sanity plugins which implement the part part:@sanity/dashboard/widget. If you want to add your own custom widget for a specific Sanity Studio, the easiest way to get started is to initate an empty plugin with the CLI:

❯ sanity init plugin

You will be asked to give your dashboard widget a name, if you want to enable it in your current project, and install its dependencies. You probably want to accept all these in order to get going.

The source code will be downloaded to the plugins folder in your project, where you can start editing the plugin.


Even though you name the plugin in the init prompt, you still have to use the same name that it has in the plugin’s sanity.json. If you initate the cats plugin, this is "name": "part:@sanity/dashboard/widget/cats". This means that you have to change "cats" to whatever you want to refer to in your Dashboard configuration ({ name: 'cats' }).

When writing your widget components, it's recommended to use the styles defined in ./src/widgets.css for your basic building blocks:

@import 'part:@sanity/base/theme/variables-style';

.container {
  composes: container from 'part:@sanity/dashboard/widget-styles';

.containerWithPadding {
  composes: containerWithPadding from 'part:@sanity/dashboard/widget-styles';

.header {
  composes: header from "part:@sanity/dashboard/widget-styles";

.title {
  composes: title from 'part:@sanity/dashboard/widget-styles';

.buttonContainer {
  composes: bottomButtonContainer from 'part:@sanity/dashboard/widget-styles';

Your widget root element should aways be wrapped with the container style from part:@sanity/dashboard/widget-styles.

You can study the source code of these widgets to get sense of how you can approach fetching of documents, adding configuration and so on:

Previous: Installing and configuring widgetsNext: Sanity Studio Deployment