Ryan Doyle

How to start from scratch with a Sanity powered Gatsby website

Making New Projects with Gatsby & Sanity

Knut Melvær

Learn how to make a What You Get Is What You Hear (WYGIWYH) editor for speech synthesis using Sanity.io’s editor for Portable Text.

How To Make A Speech Synthesis Editor

Travis Stanley

Learn how to implement localised content from Sanity in Gatsby.js

A method for Localization with Gatsby and Sanity.io

This guide will walk you through how to deploy Sanity Studio with Now in three simple steps.

Deploying Sanity Studio with ZEIT Now

Rune Botten

If you’ve used rich text with Sanity you might be familiar with the following definition of a typical body field on a document, and if not, this is a good chance to learn what it is:

This code example defines a document named 

 objects which represent the text blocks themselves. But we are of course not limited to 

 in this array or your own custom objects to allow more things than just text. Let’s make a custom object to hold a reference to an Instagram post, then provide a preview for that post in the rich text editor.

, special templating tag or similar, you might be asking yourself? Because if we only save the data (url) and what it means (instagram post), we have full flexibility later when we present it. For a web site that probably means rendering it as an iframe, object or embed tag. For other presentations like in a native mobile app or even printed media this is probably not the right choice. You might not have any other presentations than web right now, but who knows the future? Also, you probably don't want a redesign of your website to involve a redesign of all your content as well.

We'll start by creating a new file called 

 and defining an object that can hold the URL for the Instagram post. To help the editors out, lets also include a helpful text on how they can obtain the right URLs.

Before we can reference this new object in documents or from other objects we need to let Sanity Studio know about it. We do this by including it in the array of schema types in 

Now we can add it to the array of accepted content types where we define our body field in 

The editor for Portable Text Editing now looks like this:

Great! We're letting editors add and change Instagram URLs, right in the text body, but displaying the raw object data value isn’t very user friendly. We can fix that by creating a preview for the 

 object. Sanity Studio is extensible in many ways, and one of them is the ability to provide a React component for previewing your custom content in the editor.

To get a head start, we'll use an open source React component for embedding Instagram posts called 

. Install this in the folder of your Sanity Studio (

) and be sure to restart the development server (

First we create a React component that receives the URL property from the object it should preview. In this example we put the component in a file called 

. You can structure your code differently if you want, as long as you use the correct file paths in your code.

Then we import the preview component in our object definition for 

 and tell Sanity Studio to use the exported React component for the preview of its value:

And with that the editorial experience now looks like this

Very nice! Now you know how to create custom objects, allow them to be inserted amongst text blocks in the Sanity Studio rich text editor and also how to create nice previews for the data they store.

I see that there is an npm module called 

. Maybe you can create your own YouTube embed for Portable Text using what you learned in this guide?

How to embed Instagram posts in the rich text editor

In this guide you'll learn how to add an Instagram post as structured content and create a preview for it in the editor for Portable Text.

How to embed an Instagram post in Portable Text

Magnus Holm

Query JSON documents in the Terminal with GROQ

 you can override the default behavior for how the Sanity Studio lists out documents. Without any configuration, the Studio will list out your document types in the leftmost pane, a list of the documents under each type in the second, and the editor for a selected document in the third. In this guide, you’re introduced to some common use cases and central concepts for Structure Builder.

, but you should be able to tag along using your own project. All the code snippets should be copy-pasteable, but we recommend that you try typing it out to get a better feel for how the code are structured. Structure Builder is written using 

, so if you have a compatible code editor (like 

), you should be able to get auto-complete for the different methods. It should be noted that this tutorial uses regular JavaScript, and you don't need to 

 TypeScript in order to use this feature (or any feature in Sanity Studio).

The Studio comes a default structure out of the box. In order to override the default behaviour of how the documents are grouped and listed out, we have to tell the Studio that it should look for the structure elsewhere. This is done by leveraging 

. In this case you have to add an entry to the parts array in 

, located at the root level of your studio folder. That will let the Studio know where your configuration file is.

part:@sanity/base/schema

part:@sanity/desk-tool/structure

porfolio

Now you have to create and save a new file to the path you specified in 

 and we have saved the file on root in the studio folder.

If you restart the local development server (

), you will get an error message. This is because you haven’t given the Studio any structure yet. Let’s begin defining the default structure that reproduces the default behavior:

First we have to import the Structure Builder, this is a collection of methods that lets you define how the panes and lists in the Studio should work. We use the single 

 is a “convenience method" that returns a list of the document types we have defined in 

. We will return to how we can filter out those document types we don't want in this first pane.

How to make a single document (a.k.a a singleton)

A common use case for structure builder is restricting a document type to only having one document. This is for when you want to make a configuration document, some global navigation, or some singular metadata. 

In the portfolio starter we want some settings for the site with the website’s title, description, some keywords and an author. We have defined this as a document type with the name 

. For the time being, it doesn't make sense to have multiple site settings (but it's great to know that you can in the future!), so let's make it so that there is a list item called ”Settings,” and when the editor push it, it will open the editor with the fields. 

Let's go through the Settings configuration step by step:

 takes an array. Since we're adding more array items here, we have to add the array brackets (

 which creates the top item in the first pane.

To define what should happen when you click it, you need to give it a 

, which tells the Studio that when you click on the item with the title "Settings", it should return an editor in the next pane.

To specify which document type, that is, the fields, the editor should show, we use 

 for the document that's created when it's edited.

If you want to limit the create and delete actions for this single document, you can do so with the 

There's now two “Settings” items in the first pane. This is because the document type “siteSettings” is included in the 

 as well. So what we want to do next is to filter that out from this list. Since this method returns an array, we can do that with 

 we add an anonymous function (a.k.a arrow function) that has each 

Because we might want to filter out more than this one document type, we put the document type name in an array (

 is in that array. Since we want to return 

 is included in this array, we prepend it with the not operator (

If you want to get a better sense of what's going on, you can log out the 

.filter(listItem => console.log(listItem.getId()) || !['siteSettings'].includes(listItem.getId()))

) will always return the right hand expression. 

We have now learned how to override the default structure and how to make a new list with list items in it. Let's say we wanted to group the Category and the Project document types under a list item called "Portfolio" in the first pane, so that you end up with 

. The following code snippet may seem elaborate, but if you break it down, it should be possible to follow what happens:

 in the first pane and give it the title "Portfolio".

In the items array we add two list items, one for the project type, and one for the category type.

S.documenTypeList('<document type name>')

, so that when each of these items are pushed, it will open a new pane with its documents, that also has the pane menu and other things automatically set up.

 methods to override the default title and make it plural.

We use the same pattern for the person documents, only on the outmost array, which adds it to the first pane.

Finally, we add "project", "category", and "person" to the filter array, to remove the duplicated list items in the studio.

Make dynamic document list with GROQ filters

In many cases you want to group documents based on some field value or other properties. In the portfolio studio we can add references to 

 type. Let's say that we wanted to group projects by the categories they were added to. Then we first need to make a listitem for “Projects by catgory”, then list out the different categories, and make the child of those the list of projects that belongs to each category. Let's take this step by step.

To define what should appear in the next pane we add the 

Inside the child() we use the conveinence method 

. This method will also set up menu items etc.

We don't want to return the editor for categories, but the projects that refers them, so we add another 

. Instead of passing a new list the child directly, we insert an anonymous arrow function, where the selected document’s id is the parameter we have called 

 (what goes inside of the square brackets in GROQ), and the params() method let's us define what the query variable (

_type == "sampleProject" && $categoryId in categories[]._ref

 appears inside of the objects for the key 

The capabilities of Structure Builder goes beyond what we have covered in this guide. You can experiement with resolving structures asyncronously, or even with observables. You can also customize structures with icons, initial values, menu items, and use more advanced filters to get exactly what you need.  

Learn how to customize the document lists structure in the Sanity Studio

Structure builder lets you override the default document lists in the Studio, and gives full flexibility to how documents are grouped.

Getting started with Structure Builder

Alex Patterson

Anchor Links from Sanity in Gatsby

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

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

Guides

Making New Projects with Gatsby & Sanity

How To Make A Speech Synthesis Editor

A method for Localization with Gatsby and Sanity.io

Deploying Sanity Studio with ZEIT Now

How to embed an Instagram post in Portable Text

Query JSON documents in the Terminal with GROQ

Getting started with Structure Builder

Anchor Links from Sanity in Gatsby

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

Get started with the Next.js landing page website

Get started with the Nuxt.js event website

Get started with the Gatsby blog

Introduction to content modeling

Get started with the Gatsby portfolio

How to configure schemas