Knut Melvær

Sometimes you want to have a specific value in a new document. In the Sanity Studio, this is called "initial value". This guide covers how to get started with configuring initial values for a document type, from some very basic settings, to more advanced using external asynchronous APIs. It's also possible to create different initial value templates for the same document type, which you can learn more about here.

The initial value feature work only on documents created in the studio. If you create documents programmatically, you'll have to set up the same functionality in your script/application.

You configure initial values by adding the initialValue property to a document type. It can take a simple object with the field names as keys, and static values. It can also take a function or a promise.

Setting the initial values for a document type works best when it's something editors shouldn't have to think about or explicitly wants. You should assume that editors may forget to look them over before publishing. Don't use an initial value as placeholder text, it's probably better to use the field’s 

Setting a “featured” boolean field to 

A common use case is setting a boolean field to either 

 as a new document initial value. The boolean is initially 

, meaning that the editor hasn't interacted with it. Let's say we have a simple category type, and some of these can be featured.

 property on the document type and set the field and value inside of it like this:

If you have the studio running on local, you can now save your changes and test out if it works by creating a new category document. The 

Setting an initial date to the current time

Another common case for initial values is to automatically set a datetime field to the current time when creating a new document, keeping the possibility of setting the date manually to schedule it. Since we now don't just have static values, but need to run the 

 function, we have to also return a function to the 

Often you have reference fields in your document types. In the blog starters on sanity.io/create the posts are set up with an array (because there always comes a time where you need more than one) of authors, which are references to the author document. Let's say you are mostly the only author, and it makes sense to have that as the initial value for a new blog post.

The way to do this is to set the author reference object as the initial value in an array on the post document. To find this data structure, you can open an existing blog post with the author that you want, go into the inspect view (the menu in the top right corner of the document form, or 

 property in the array object. Sanity Studio uses this for the real-time editing. If you don't add the 

 the Studio will prompt you to add it afterwards.

Setting the initial value dynamically from a query

Let's say you have authors with different responsibilities expressed as strings in a 

 array field on the author document type, which can be the strings 

. The content model looks something like this:

Now you want to set all the authors with the marketing responsibility as the initial value for the authors array for new blog posts. You could take the approach in the last section and find all the 

s for the documents and put them in as the initial value, but it wouldn't work if you shifted the responsibilities around, or added new. 

What's super cool (and powerful) with the 

 property is that you can return an asynchronous function, i.e., a promise, which means you can run queries inside of it to construct your initial value. In this example, we import the built-in client that comes with the studio and use it to run a GROQ query that finds these authors, then project the correct data structure.

Here we're using the Sanity client to run queries on the Studio’s connected dataset, but you could of course run any async function here, including fetch to an external API endpoint (to get the current weather or something). 

If you plan to query external API endpoints, you might hit problems with 

 since the request comes from your browser. Be careful with how you operate with secrets and tokens. If you put them into the schema code, they might be exposed.

Setting the browser’s current geolocation as the initial value

Since the Studio runs in the browser, it can also use its APIs to set some initial values. Let's say you want to record the geolocation of where a document was created (be mindful of privacy issues). We can use the 

Running this code makes the Studio prompt the editor for permission to access the location. And for this to work, the editor has to allow the Studio getting the position. We also need to wrap the 

Install one of the maps input components (

) to get a nicer interface for location data.

We have now learned different ways of setting initial values for a document type. The next step is to explore how you can create templates for initial values to make it possible for editors to select between different sets of initial values for the same document type. 

Check out the documentation for more on this topic

Create the initial value for a new document in Sanity Studio. This guide takes you through simple and advanced use cases. 

Getting started with initial values for new documents

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 

A detailed guide of how to import external data into Sanity

Guides

Getting started with initial values for new documents

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