How to Brand your Sanity Studio

At Sanity, we have made sure that our editing environment, the Studio, comes with a default look that is easy to use and great look at, but sometimes you want to customize it to your own liking. In other systems you would need to provide custom CSS to override selectors, creating brittle dependencies, or change the internal CSS and thereby making future upgrades hard. However, in Sanity you can extend and customize the Studio to your heart's desire, thanks to the parts system at the core of Sanity. This includes adding your own logo to the navigation bar and creating custom looks for the Studio by overriding CSS variables.

In this tutorial, you will learn how to brand your Studio with a custom logo, colors and typography to make your Sanity Studio stand our from the crowd and feel true to your brand.

What is Sanity?

Sanity.io is a platform for structured content with an open source editing environment. Sanity Studio is a single page application written in React, where you can configure the document types and input fields, with simple JavaScript objects. The Studio connects to Sanity’s hosted real-time APIs. You can also customize the Studio with your own input components, plugins, and tools.

Setting up your Studio

For this tutorial we created a new Sanity project with the Sanity CLI by running sanity init in our terminal. We decided to use the e-commerce template to show you a Studio pre-populated with sample data that helps demonstrate the impact custom branding can have on your Studio.

You are free to choose how you want to follow along in this tutorial. You can create a project the same way we did with sanity init, create a project with the Sanity jumpstart templates on sanity.io/create, or simply follow along with your own Sanity project.

Here is the full configuration for the project we created for this tutorial as a reference.

$ sanity init
You're setting up a new project!
We'll make sure you have an account with Sanity.io. Then we'll
install an open-source JS content editor that connects to
the real-time hosted API on Sanity.io. Hang on.
Press ctrl + C at any time to quit.

Looks like you already have a Sanity-account. Sweet!

? Select project to use: Create new project
? Informal name for your project: studio-branding
? Name of your first dataset: production
? Choose dataset visibility – this can be changed later: Public (world readable)
? Output path: /Users/vicbergquist/Desktop/studio-branding
? Select project template: E-commerce (schema + sample data)
? Upload a sampling of products to go with your e-commerce schema? Yes
✔ Bootstrapping files from template
✔ Resolving latest module versions
✔ Creating default project files

✔ Saved lockfile
✔ [100%] Fetching available datasets
✔ [100%] Reading/validating data file (70ms)
✔ [100%] Importing documents (329ms)
✔ [100%] Importing assets (files/images) (15.86s)
✔ [100%] Setting asset references to documents (325ms)
✔ [100%] Strengthening references (288ms)
Done! Imported 32 documents to dataset "production"

To inspect the code behind your Sanity Studio and to get started with this tutorial, open the Sanity project folder in your favorite code editor. This is where you will be spending most of your time during this tutorial.

To learn more about the Studio and its project structure, see our documentation.

To explore the default Studio, run sanity start from the terminal while at the root of your project. This will compile all the necessary files and serve the Studio with Hot Module Replacement (HMR):

$ cd path/to/your/project
$ sanity start
$ Content Studio successfully compiled! Go to http://localhost:3333

You should now have a Studio running locally. Open it in your favorite browser.

Because we used the e-commerce template, our Studio now looks like this. With the desk tool (a built in way to navigate your content) we selected a product from our content to show you the default style of the Studio. Notice that we currently do not have a logo on the left side of the navigation bar, the Studio uses our project name there instead.

Adding a custom logo

To add a logo to your Studio, you need to implement a part called brand-logo in your project's configuration file, sanity.json. This part uses a custom React component to render your logo.

First, create a js file for your component and import React as a dependency. Then write a React component that returns the logo you want in the navigation bar, and save your changes. Remember that this is a regular React component that can render the logo any way you want, including as an SVG.

Here is the logo component we just created as an example. It's in a file called myLogo.js placed in a logo-folder at the root of our project. Note that we are returning an image from the static folder using its relative file path.

// ./logo/myLogo.js

import React from 'react'

const myLogo = () => (
  <img src="/static/lionqueen.png" alt="Lion Queen"/>
)

export default myLogo

Next, at the root of your project, find the sanity.json file. This is where you will find all the information about your project, including all parts and plugins you have installed and implemented (or that comes with the template you use).

This is our sanity.json. Your project name, ID, and dataset may differ.

{
  "root": true,
  "project": {
    "name": "studio-branding"
  },
  "api": {
    "projectId": "ym8ladyp",
    "dataset": "production"
  },
  "plugins": [
    "@sanity/base",
    "@sanity/components",
    "@sanity/default-layout",
    "@sanity/default-login",
    "@sanity/desk-tool",
    "barcode-input"
  ],
  "parts": [
    {
      "name": "part:@sanity/base/schema",
      "path": "./schemas/schema.js"
    }
  ]
}

To make the logo actually show up in your Studio, you have to add it to the parts-array in sanity.json. This is the only way for Sanity knows that you want to use a custom component to render your logo, instead of using your project name in the navigation bar.

Create a new object that has implements and path keys. Give implements the value of part:@sanity/base/brand-logo, which is the full name of the brand-logo part, and point path to the file with your logo component by giving it a value of the file's relative path.

You are free to decide where you place files associated with parts in your project folder and what you name them, but you need to make sure the part's path has the correct relative file path.

In our case, we created a logo-folder at the root of our project and wrote our logo component in myLogo.js. The parts array in our sanity.json configuration file now has a new object that reflects that:

{
  ...,
  "parts": [
    ...,
    {
      "implements": "part:@sanity/base/brand-logo",
      "path": "./logo/myLogo.js"
    }
  ]
}

To make sure Sanity implements this new part and your logo component correctly, you need to force quit the current sanity start command in your terminal (ctrl + C) and run sanity start again.

Now, Sanity implements the part correctly and knows it should use the component you created to render your logo in the right place. See it in action in your Studio by switching back to your browser and refreshing the page! Here is our logo:

Now that you have a custom logo, you might wonder how you can apply styles to it. We certainly do, as our logo does not have the right size for the navigation bar. It's currently oversized. Depending on where you put your logo component file, you can create a CSS file in the same place and write styles to target your logo.

To demonstrate, we created a myLogo.css file in the same logo folder as our myLogo.js component and adjusted the height:

/* ./logo/myLogo.css */

.myLogo {
  height: 100%;
  max-height: 3rem;
}

To actually apply the styles you write for your logo, you import the CSS file in the logo component and make them available on a styles object. Now you can access them with JSX by using dot notation.

For example, here we import our styles in myLogo.js and give our img tag a className of styles.myLogo:

// ./logo/myLogo.js

import React from 'react'
import styles from './myLogo.css'

const myLogo = () => (
  <img className={styles.myLogo} src="/static/lionqueen.png" alt="Lion Queen" />
)

export default myLogo

Sanity uses PostCSS with css-modules to isolate styles to components. You are not strictly bound to use css-modules, but we highly recommend it, and we use this approach in this tutorial.

Looking at our Studio in our browser, we can now see our logo, properly sized, in the navigation bar!

Styling the Studio

Now that your Studio uses a custom logo, you might want to style and brand the rest of your Studio! This is easily achieved by implementing another part called override-style, which exposes a wide range of CSS variables that you can override with your own values to change the default look of the Studio.

For this tutorial, we will show you how to change the brand colors and typography of the Studio. However, you can can customize the look of the Studio even further. Feel free to explore the full list of available CSS variables on GitHub and go beyond what this tutorial covers.

To get started, you need to implement the new override-style part in your sanity.json configuration the same way you implemented the brand-logo part.

Create a new object in the parts array that implements part:@sanity/base/theme/variables/override-style and points to the path of a CSS file.

{
  ...,
  "parts": [
    ...,
    {
      "implements": "part:@sanity/base/brand-logo",
      "path": "./logo/myLogo.js"
    },
    {
      "implements": "part:@sanity/base/theme/variables/override-style",
      "path": "./styles/variables.css"
    }
  ]
}

Here you can see that we created a variables.css-file inside a styles-folder at the root of our project. Remember that you are free to decide where files associated with parts go and how you name them.

Save your latest changes, and force quit the current sanity start command in the terminal (ctrl + C) to make sure that Sanity implements this new part correctly. Restart the Studio by running sanity start again.

We created a theme for this tutorial to show you how the look of the Studio changes by customizing the brand colors, typography and navigation bar. However, you are free to choose your own colors and values, or even use any other variables, while following this tutorial.

Brand Colors

You can now start editing the CSS file you created for the override-style part and see your changes live in the Studio.

The first step to a custom Studio look is declaring the CSS variables you want to override with custom values on the :root pseudo-class. If you don't, your Studio won't apply any changes you make.

Override the primary and secondary colors of the Studio, --brand-primary and --brand-secondary, along with their inverted equivalents to change the basic brand colors of your Studio. Find the full list of available brand color variables on GitHub. Here are our changes:

/* ./styles/variables.css */

:root {
  /* Brand colors */
  --brand-primary: #cc4a1e;
  --brand-primary--inverted: #ffffff;
  --brand-secondary: #ffa800;
  --brand-secondary--inverted: #3c1609;
}

After saving your changes, see them live in your Studio in your browser.

You can see that the Studio no longer uses the default blue as the brand color, but the color you set as your primary color. This also applies to hovered items, some buttons and focused input fields. You should also notice that the color of your navigation bar has changed slightly.

Here is our example Studio with our new brand colors:

Typography

Next, let's change the typography of your Studio. You can change a wide range of typography variables, but let's start with the basics.

To change the font that your Studio uses, you have to override the base font family with --font-family-base. You can also change the font size with --font-size-base and text color with --text-color. If you would like to use an external font, you can import it at the top of the file.

Change the font family to Nunito, the font size to 18px and use the inverted version of the secondary brand color as the text color for the whole Studio.

/* ./styles/variables.css */

@import url('https://fonts.googleapis.com/css?family=Nunito&display=swap');

:root {
  /* Brand colors */
  --brand-primary: #cc4a1e;
  --brand-primary--inverted: #ffffff;
  --brand-secondary: #ffa800;
  --brand-secondary--inverted: #3c1609;
  /* Typography */
  --font-family-base: 'Nunito';
  --font-size-base: 18px;
  --text-color: var(--brand-secondary--inverted);
}

Nunito is an external font from Google Fonts. For it to work in the Studio, we first need to import it from the Google Fonts API.

To see your changes live, save them and switch back to your browser. Here is our example Studio with the new typography we declared above.

The Navigation Bar

The navigation bar uses the primary brand color to calculate its background color and the text color. However, you might want completely different colors for the navigation bar in your Studio.

To override the default look of the navigation bar, you can use --main-navigation-color to change the background color, and --main-navigation-color--inverted to change the text color. You can find these variables, and more, in the globals.css file.

Change the color of the navigation bar to the same color as --brand-secondary and the navigation text to --brand-secondary--inverted.

/* ./styles/variables.css */

@import url('https://fonts.googleapis.com/css?family=Nunito&display=swap');

:root {
  /* Brand colors */
  --brand-primary: #D2613A;
  --brand-primary--inverted: #ffffff;
  --brand-secondary: #FFB320;
  --brand-secondary--inverted: #3c1609;
  /* Typography */
  --font-family-sans-serif: 'Nunito';
  --font-size-base: 18px;
  --text-color: var(--brand-secondary--inverted);
  /* Main Navigation */
  --main-navigation-color: var(--brand-secondary);
  --main-navigation-color--inverted: var(--brand-secondary--inverted);
}

Remember to save any changes you made to see them live in the Studio. This is our example Studio with custom navigation colors:

Conclusion

Your Studio may now look very different from the Studio you started out with, ours certainly does, and depending on the variables you chose to override, your Studio will have completely transformed. Here is a side-by-side comparison of the Studio we started out with for this tutorial and our freshly branded Studio:

While this tutorial only covered the implementation of two Sanity parts, they are only a few of the many you can add to further extend and customize the functionality of your Sanity Studio. You can also install collections of parts, also known as plugins, create custom input components and change the way you navigate your Studio content by customizing the desk tool with the Structure builder. The Sanity world is now your oyster!

To learn more about styling the Studio, take a look at our official documentation. You can also inspect the code behind our example Studio branding on Github, or even install the custom styles we applied as a plugin by running sanity install lion-queen-theme from the terminal while at the root of your project.

We hope you enjoyed this tutorial and would love to see how you customized your Studio, so feel free to share it with us in the comments, in the #i-made-this channel in our Slack community, or on Twitter!