Thomas Drevon

The Sanity Studio grants a developer the power to create pretty much any editing experience. The 

 which are built into Sanity (string, boolean, image etc) all come with their own input components and will help you build UIs for most use-cases.

But let's say we are creating landing pages for a brick-and-mortar store, and we want to give editors the ability to update the opening hours for each day of the week.

It seldom makes sense to reinvent the wheel, and since custom input components can be shared on NPM like any other JavaScript package, we would typically start by checking 

 if someone else has already open-sourced something we can reuse. 

For this tutorial we're pretending the above search turned up empty. No problem at all, let's do this ourselves!

) is a perfect fit. We want user input to be formatted as 

Sure, we can achieve this by using a vanilla 

 input for both day and time, but let's aim for a user interface which editors will enjoy and which guarantees properly formatted data. It's time for a custom input component!

This guide will move through the following steps:

Create a schema type which will enable day & time input

Configure the Sanity Studio to use our new type

Implement a React component which renders a time-picker widget and sends incoming data to the Sanity Backend

First off, we need a Sanity Studio as playground. You probably have one of those already. If you do, feel free to stick with what you're familiar with. However, if you want to start with a blank slate, you have two options:

Open your terminal and ensure you have the latest Sanity CLI package

 you'll get some prompts. If you are unsure what to choose, go with "Create new project", choose the blog template and run with the defaults on the rest of the prompts.

Go to [sanity.io/create](https://www.sanity.io/create)

Select a template, e.g. Next.js Landing Pages and follow all the steps

You now have a Studio + Frontend! And they're both deployed to 

 and thus running independently of your computer. However, for the development we are about to do, you need the source code on your local computer. Now is the time to clone your newly created GitHub repository. If you're unsure how to do that, 

Whichever of the two options you chose, you now have a Sanity Studio ready to run on your local computer.


Change directory to where your Studio code is located, ensure all dependencies are installed, and start up the Sanity Studio:

🔥 Congratulations! You now have a Sanity Studio running on your local computer! The Studio connects to the Sanity backend and it renders a UI which enables you to edit your cloud-stored data.


It's time to open your favorite code editor start the customization!

Let us reason a bit about how to keep track of our opening hours. It might make sense to keep an array of objects, where each object represents a day of the week, along with two distinct points in time, one for when the store opens and the other for when it closes.

We're going to call the array openingHours. Each object therein will be dayAndTime objects, which in turn consist of three fields: day, opensAt and closesAt.

This is nice! We have settled on the shape of our data, but we also need a document type to keep it in. Let's create a new file schemas/documents/store.js which defines a store document:

👉 Beware that during the below editing, a running Studio will crash. Don't worry, this is because our code is referring to stuff that hasn't yet been implemented. We'll deal with that very soon!

 and add the following code to that file:

There are a few things going on here, so let's run through each in turn. Numbers follow the comments in the code above.

 react component which serves as our custom input component (see implementation below). You can read more about 

A hard coded list of which days the editor may choose from. We use these in the 

The validate function is invoked when the editor changes a value. If all is well, this function should return 

. If the input does not validate, this function should return  a humanly readable 

 in this case) and call the function which  evaluates user input. More on validation 

 from a predefined list of strings (names of days in this case). You may use 

Enable the editor to input a point in time, stored as 

, using a our soon-to-be-defined TimeInput custom input component.

Same as above, but the time string is stored to 

 object will render as a list item in the Sanity Studio. More on preview 

Finally, we need to make our Studio is aware that the new 

 file and import + append them to schema types array:

Oh yes! The schema is in place! Now, let's implement the component!

For the actual UI widget, we're going to use 

. True, this particular choice may not be a thing of transcendent beauty. And there does exists plenty of open-source 

...isn't trivial. If you know of such a package, let me know and I'll be happy to update this guide!


Disclaimer done. It's time to install some needed dependencies to the Studio:

And create a folder for the code to live in:

A quick summary of what's going on, same sequence as the comments:

Import react-timepicker CSS. Yes, we're starting off with an ugly hack which imports the react-timepicker CSS into our component. In a better world, the timepicker would have handled this "under the hood". Sadly, we don't live in that world 😭

A function which transform hours and minutes to a formatted time string. E.g. the numbers 

A function which transforms a formatted time string to an object with hours and minutes. E.g. `

 based on an updated time value. This eventually performs an HTTP request to the Sanity backend, notifying that this particular field should change it's value

Declare shape of our component's properties. The 

A function called by the Sanity form-builder when this input should receive focus

A function called whenever the editor changes a value

` if you want title and description rendered like any other input field

` with current hours + minutes and have it call back on user input

Good job! Let's give our new UI a spin! Run 

Under "Opening Hours", clicking the "Add" button will bring up a modal looking something like this:

And once you have entered some data, the preview function we defined in the 

 schema type will produce something like this:

Some style customization is usually of needed! Say we want border of solid gold surrounding our time-picker (to make it look expensive) and also a hover effect which makes the background pink! To do that, we need to wire up our own CSS. Open 

 and add this line somewhere near the top:

Step-by-step guide to create a custom input component

How to make a Custom Input Component

Victoria Bergquist

At Sanity, we have made sure that our editing environment, the Studio, comes with a default look that is easy to use and great to 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 

 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.

 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.

For this tutorial we created a new Sanity project with the 

 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 

, create a project with the Sanity jumpstart templates on 

, 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.

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 

 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):

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.

The e-commerce Studio template with Kick Lakris as the selected product from the sample data.

To add a logo to your Studio, you need to implement a 

. This part uses a custom React component to render your logo.

 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 

-folder at the root of our project. Note that we are returning an image from the 

Next, at the root of your project, find the 

 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).

. Your project name, ID, and dataset may differ.

part:@sanity/base/schema

studio-branding

To make the logo actually show up in your Studio, you have to add it to the 

. This is the only way for Sanity to know that you want to use a custom component to render your logo, instead of using your project name in the navigation bar.

 to the file with your logo component by giving it a value of the file's relative path.

You are free to decide where in your project folder you place files associated with 

 and what you name them, but you need to make sure the part's 

-folder at the root of our project and wrote our logo component in 

 configuration file now has a new object that reflects that:

To make sure Sanity implements this new part and your logo component correctly, you need to force quit the current 

Now, Sanity 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 actually apply the styles you write for your logo, you import the CSS file in the logo component and make them available on a 

object. Now you can access them with JSX by using dot notation.

For example, here we import our styles in 

 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 see that our logo is now properly sized in the navigation bar!

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 

, 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 

 on GitHub and go beyond what this tutorial covers.

To get started, you need to implement the new 

part:@sanity/base/theme/variables/override-style

 and points to the relative path of a CSS file.

-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 

) to make sure that Sanity implements this new part correctly. Restart the Studio by running 

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 

You can now start editing the CSS file you created for the 

 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 

 pseudo-class. If you don't, your Studio won't apply any changes you make.

Override the primary and secondary colors of the Studio, 

, along with their inverted equivalents to change the basic brand colors of your Studio. Find the full list of available 

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 and some buttons and selected 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:

Next, let's change the typography of your Studio. You can change a wide range of 

To change the font that your Studio uses, you have to override the base font family with 

. You can also change the font size with 

. If you would like to use an external font, you can import it at the top of the file. the 

 and use the inverted version of the secondary brand color as the text color for the whole Studio.

 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.

 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 

 to change the text color. You can find these variables, and more, in the 

Change the color of the navigation bar to the same color as 

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

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 

, they are only a few of the many you can add to further extend and customize the functionality of your Sanity Studio. You can install collections of parts, also known as 

 and change the way you navigate your Studio content by customizing the desk tool with the 

To learn more about styling the Studio, take a look at our 

. You can also inspect the code behind our example Studio on Github, or even install the custom styles we applied as a plugin by running 

 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 #i-made-this channel in our 

Customize the look and feel of the Sanity studio to your own liking. 

At Sanity, we have made sure that our editing environment, the Studio, comes with a default look that is easy to use and great to look at, but sometimes you want to customize it to your own liking.

 How to Brand your Studio

Bjørge Næss

In this guide we will cover how to do a one-time import from an external data source using Node.JS.

Concepts you should have basic familiarity with:

What are some common external sources? An external datasource can be a wide range of different formats made available on a wide range of different transport layers. Here's a few examples:

A text file with comma separated values (CSV)

A JSON file or newline delimited JSON (NDJSON) file

No matter what kind of source you are reading from, an external import can be split into three discrete steps:

Transform to sanity document(s) matcing your data model 

Save the documents to your sanity dataset

Let's start with a simple example where the externa data source is an API endpoint file containing an array of two breeds of cats that we want to import into a sanity dataset.

The quickest way to read from this API in Node.js is to install the 

-like API that enables you to fetch the data with

Step 2: Transform to sanity document(s) matching your data model

Now, let's say the following is the Sanity schema we want our imported data to adhere to:

If you look carefully, you'll see that the source data doesn't map 1:1 to the schema model. According to our sanity schema, a cat breed will be stored like this:

Instead of importing country directly, we want a separate record of the country, and  have the country field be a reference to it instead.

 field from the external API isn't relevant to us, and we don't want to import it at all.

To further complicate things, this API does not provide any ID to uniquely identify each record.

This can roughly be codified to the following transform function:

So when importing data from an external data source, you usually want to be able to run the import several times without adding new records every time (we developers hardly ever get it right the first time, right?). It is usually a good idea to think about ways of uniquely identifying each record from an external source. Since 

, a neat trick is to assign ID's to your documents before submitting them to the sanity datastore. If you do this together with the 

 mutation you will ensure that you never get duplicate records when running the import multiple times. Note: you still need to make sure the ID doesn't collide with other documents and that it adheres to the format of 

Luckily, the array entries returned from the cat API all seems to all have an unique id. So let's use that as a part of the sanity document id. In order to avoid collisions with other documents it's a good idea to prefix the id with something, in this case we'll prefix the external id with `imported-cat-`. (As a bonus, this also makes it easy to identify documents coming from external sources). 

Going back to our transform function, we can specify the ID like this:

Now the remaining question is how do we create a reference to the country record? There's two things to keep in mind here:

When creating a reference, the document you are referring to needs to exist already. Sanity will not allow you to create references to documents that do not exist*

For each country you may encounter we only want a single record

But let's worry about a single thing at a time. It's always a good thing to keep the transformation separate from the actual posting, so to begin with let's just return all the documents we need, and then worry about the order of things after.

 function return a single document, let's make it return both the transformed cat 

Now our transform function returns two documents for every cat instead of one, and there's likely to be a lot of duplicate country-documents in there, but let's save the optimization for later.

Now we have all the documents we want to import into the sanity datastore.

In the previous steps all we did was fetch and prepare the data to be imported into your sanity dataset. Now it's time to actually make it become sanity documents.

Note: the next step is also covered in the 

First we need to confgure our sanity client with our projectId and the dataset we want to store the JSON documents in.

We will need to add @sanity/client as a dependency to our project, and import the client factory and create a client instance for our projectId and dataset:

In order to give this client write access, we need to generate an access token. You can generate an access token under the API section of your project's settings on 

Now that we have our sanity client configured, the next step is to create our documents in the Sanity dataset. All write operations are done by submitting 

 API endpoint. The Sanity.io API supports a range of mutations types that allows you to formulate a fine grained description of the write operation you want to do: 

The sanity client we just configured makes submitting mutations a matter of calling a method. Here's an example: 

All the mutation types have a corresponding method on the client instance. See the 

Going back to our example, we now want to take the documents that we have transformed to sanity documents, and write them to our dataset.

Since we're likely to want to tweak and fine tune our import script, we should cater for running it several times. This is a perfect fit for the 

 mutation, as it will create the document if it doesn't already exist, or replace it if it does exist (The create-mutation will fail if you try to create a document with an id that's already taken).

 if you want your import script to error if the document already exists.

 if you only want to import missing data. This is suitable when you are importing data from a legacy system and want to refine and modify data after it has been imported to sanity, e.g. using sanity as the 

 if the external data source should be considered the 

, and you want to discard any edits done in sanity since the previous import. In this case you may want to make the schema type 

 to prevent edits in the Content Studio that will be overwritten by running the import/sync script.

There's also more advanced ways of dealing with syncing data from external sources which involves diffing and patching.

A detailed guide of how to import external data into Sanity

Guides

How to make a Custom Input Component

How to Brand your Studio

Importing data from external sources

How to add a custom YouTube block

Internal and external links

Introduction to Portable Text

The Next.js Landing Page Website

The Nuxt.js Event Website

The Gatsby Blog

Introduction to content modeling

The Gatsby Portfolio

How to configure schemas