@tinloof/sanity-studio
v1.15.5
Published
A collection of Sanity studio plugins, fields, and components
Downloads
7,168
Readme
@tinloof/sanity-studio
A collection of studio plugins, fields, and components to boost your Sanity studio. This package provides both high-level utilities for rapid development and modular schema components for fine-grained control over your Sanity schemas.
Installation
npm install @tinloof/sanity-studioTable of contents
- Table of contents
- Schema utilities
- Schema components
- Pages
- Sections
documentI18n(DEPRECATED)localizedItemsingletonListItem- Schemas
- Disable creation plugin
- Input with characters count
Schema utilities
Field groups
Pre-configured field groups for organizing document fields.
contentSchemaGroup
A field group for content-related fields with a compose icon.
import {contentSchemaGroup} from "@tinloof/sanity-studio";
export default defineType({
name: "post",
type: "document",
groups: [contentSchemaGroup],
fields: [
// Your content fields
],
});settingsSchemaGroup
A field group for settings-related fields with a cog icon.
import {settingsSchemaGroup} from "@tinloof/sanity-studio";
export default defineType({
name: "post",
type: "document",
groups: [settingsSchemaGroup],
fields: [
// Your settings fields
],
});mediaSchemaGroup
A field group for media-related fields with an image icon.
import {mediaSchemaGroup} from "@tinloof/sanity-studio";
export default defineType({
name: "post",
type: "document",
groups: [mediaSchemaGroup],
fields: [
defineField({
name: "featuredImage",
type: "image",
group: "media",
}),
],
});navigationSchemaGroup
A field group for navigation-related fields with a link icon.
import {navigationSchemaGroup} from "@tinloof/sanity-studio";
export default defineType({
name: "page",
type: "document",
groups: [navigationSchemaGroup],
fields: [
defineField({
name: "menuItems",
type: "array",
group: "navigation",
}),
],
});ecommerceSchemaGroup
A field group for e-commerce-related fields with a tag icon.
import {ecommerceSchemaGroup} from "@tinloof/sanity-studio";
export default defineType({
name: "product",
type: "document",
groups: [ecommerceSchemaGroup],
fields: [
defineField({
name: "price",
type: "number",
group: "ecommerce",
}),
],
});eventsSchemaGroup
A field group for event-related fields with a calendar icon.
import {eventsSchemaGroup} from "@tinloof/sanity-studio";
export default defineType({
name: "event",
type: "document",
groups: [eventsSchemaGroup],
fields: [
defineField({
name: "eventDate",
type: "datetime",
group: "events",
}),
],
});formsSchemaGroup
A field group for form-related fields with a document icon.
import {formsSchemaGroup} from "@tinloof/sanity-studio";
export default defineType({
name: "contactForm",
type: "document",
groups: [formsSchemaGroup],
fields: [
defineField({
name: "formFields",
type: "array",
group: "forms",
}),
],
});analyticsSchemaGroup
A field group for analytics-related fields with a chart icon.
import {analyticsSchemaGroup} from "@tinloof/sanity-studio";
export default defineType({
name: "page",
type: "document",
groups: [analyticsSchemaGroup],
fields: [
defineField({
name: "trackingCode",
type: "string",
group: "analytics",
}),
],
});socialSchemaGroup
A field group for social media-related fields with a share icon.
import {socialSchemaGroup} from "@tinloof/sanity-studio";
export default defineType({
name: "post",
type: "document",
groups: [socialSchemaGroup],
fields: [
defineField({
name: "socialLinks",
type: "array",
group: "social",
}),
],
});localizationSchemaGroup
A field group for localization-related fields with an earth globe icon.
import {localizationSchemaGroup} from "@tinloof/sanity-studio";
export default defineType({
name: "page",
type: "document",
groups: [localizationSchemaGroup],
fields: [
defineField({
name: "translations",
type: "array",
group: "localization",
}),
],
});locationSchemaGroup
A field group for location-related fields with a pin icon.
import {locationSchemaGroup} from "@tinloof/sanity-studio";
export default defineType({
name: "venue",
type: "document",
groups: [locationSchemaGroup],
fields: [
defineField({
name: "address",
type: "string",
group: "location",
}),
],
});themingSchemaGroup
A field group for theming-related fields with a color wheel icon.
import {themingSchemaGroup} from "@tinloof/sanity-studio";
export default defineType({
name: "theme",
type: "document",
groups: [themingSchemaGroup],
fields: [
defineField({
name: "primaryColor",
type: "string",
group: "theming",
}),
],
});Array fields
Reusable array field definitions for common use cases.
sectionsBodyArraySchema
Creates a sections body array field schema for Sanity Studio. This function generates a field definition for an array of sections that can be used in document schemas. It operates synchronously and requires a sections array to be provided.
Basic usage
import {sectionsBodyArraySchema} from "@tinloof/sanity-studio";
// Basic usage with sections array
export default defineType({
name: "page",
type: "document",
fields: [
sectionsBodyArraySchema({
sections: [
{name: "hero", title: "Hero Section"},
{name: "banner", title: "Banner Section"},
],
}),
],
});
// With custom preview image function
export default defineType({
name: "page",
type: "document",
fields: [
sectionsBodyArraySchema({
sections: [
{name: "hero", title: "Hero Section"},
{name: "banner", title: "Banner Section"},
],
previewImage: (type) =>
`/static/sections/${type.replace("section.", "")}.png`,
}),
],
});Usage with provided sections
import {sectionsBodyArraySchema} from "@tinloof/sanity-studio";
const field = sectionsBodyArraySchema({
sections: [
{name: "hero", title: "Hero Section"},
{name: "banner", title: "Banner Section"},
],
previewImage: (type) =>
`/static/sections/${type.replace("section.", "")}.png`,
});Custom preview image function
import {sectionsBodyArraySchema} from "@tinloof/sanity-studio";
const field = sectionsBodyArraySchema({
sections: [
{name: "hero", title: "Hero Section"},
{name: "banner", title: "Banner Section"},
],
previewImage: (type) => `/custom/path/${type.replace("section.", "")}.jpg`,
});Parameters
props.sections- Required array of section schemas that will be available in the array field.props.previewImage- Optional function to generate preview image URLs for sections in the insert menu. Takes the section type as a parameter and returns the image URL.
The field includes:
- Grid view insert menu - Visual section picker with preview images
- Customizable preview images - Configure image paths and naming conventions
- Type-safe configuration - Full TypeScript support with proper return types
Object fields
Reusable object field definitions for common use cases.
seoObjectField
A comprehensive SEO object field with configurable sub-fields using the FieldCustomization system.
import {seoObjectField} from "@tinloof/sanity-studio";
export default defineType({
name: "post",
type: "document",
fields: [
seoObjectField({
indexableStatus: true, // Show indexable status (FieldCustomization)
title: "hidden", // Hide SEO title (FieldCustomization)
description: (field) =>
defineField({
...field,
title: "Meta Description",
validation: (Rule) => Rule.max(160).required(),
}), // Custom field transformation (FieldCustomization)
ogImage: false, // Remove OG image completely (FieldCustomization)
}),
],
});The field includes:
- Indexable status - Controls search engine indexing
- SEO title - With character count validation (15-70 chars)
- SEO description - With character count validation (50-160 chars)
- Social sharing image - For Open Graph and social media
Each sub-field supports the full FieldCustomization system (true, false, "hidden", or transform function).
Slug fields
Specialized slug field definitions with enhanced functionality.
pathnameSlugField
A pathname slug field with internationalization and folder support.
import {pathnameSlugField} from "@tinloof/sanity-studio";
export default defineType({
name: "page",
type: "document",
fields: [
pathnameSlugField({
localized: true, // Enable internationalization
defaultLocaleId: "en", // Default locale for i18n
hidden: false, // Show/hide the field
disableCreation: false, // Disable editing in production
options: {
initialValue: "/", // Initial pathname value
autoNavigate: true, // Auto-navigate in Presentation
prefix: "/blog", // Pathname prefix
folder: {
canUnlock: false, // Disable folder renaming
},
},
}),
],
});String fields
Common string field definitions for document metadata.
internalTitleStringField
A string field for internal document identification.
import {internalTitleStringField} from "@tinloof/sanity-studio";
export default defineType({
name: "post",
type: "document",
fields: [
internalTitleStringField, // Always includes description and group settings
],
});localeStringField
A hidden string field for locale identification in internationalized documents.
import {localeStringField} from "@tinloof/sanity-studio";
export default defineType({
name: "post",
type: "document",
fields: [
localeStringField, // Hidden field for locale tracking
],
});Pages
Pages is a plugin that wraps Presentation to display your website pages in a sitemap-like navigation and make it possible to create new ones.
Basic usage
1. Configure Pages:
import {pages} from "@tinloof/sanity-studio";
export default defineConfig({
// ... other Sanity Studio config
plugins: [
pages({
// Presentation's configuration
previewUrl: {
previewMode: {
enable: "/api/draft",
},
},
}),
],
});2. Add a pathname field to page schemas using the definePathname helper:
import {definePathname} from "@tinloof/sanity-studio";
export default defineType({
type: "document",
name: "modularPage",
fields: [
definePathname({
name: "pathname",
}),
],
});Documents with a defined pathname field value are now recognized as pages and are automatically grouped into directories in the pages navigator.
Like Sanity's native slug type, the pathname supports a source option which can be used to generate the pathname from another field on the document, eg. the title:
import {definePathname} from "@tinloof/sanity-studio";
export default defineType({
type: "document",
name: "modularPage",
fields: [
definePathname({
name: "pathname",
options: {
source: "title",
},
}),
],
});The source can also be a function (which can be asynchronous), returning the generated pathname.
Enabling page creation
Use the creatablePages option to define which schema types can be used to create pages.
When a page is created, it will automatically have the current folder in its pathname.
import {pages} from "@tinloof/sanity-studio";
export default defineConfig({
// ... other Sanity Studio config
plugins: [
pages({
// Add any documents you want to be creatable from the pages navigator
creatablePages: ["page"],
previewUrl: {
previewMode: {
enable: "/api/draft",
},
},
}),
],
});Enabling internationalization
The i18n option can be used to support filtering pages by a locale field and display internationalized URLs.
When page creation is enabled, the currently selected locale is also used as an initial value to create new pages.
Path names are automatically validated to be unique across locales.
import {pages} from "@tinloof/sanity-studio";
const i18nConfig = {
locales: [
{id: "en", title: "English"},
{id: "fr", title: "French"},
],
defaultLocaleId: "en",
};
export default defineConfig({
// ... other Sanity Studio config
plugins: [
pages({
i18n: i18nConfig,
previewUrl: {
previewMode: {
enable: "/api/draft",
},
},
}),
],
});
/**
* Don't forget to add i18n options and locale field to your document schema
*/
export default defineType({
type: "document",
name: "page",
fields: [
definePathname({
name: "pathname",
options: {
// Add i18n options
i18n: {
enabled: true,
defaultLocaleId: i18nConfig.defaultLocaleId,
},
},
}),
// Add locale field
defineField({
type: "string",
name: "locale",
hidden: true,
}),
],
});Filtering pages based on user roles
The filterBasedOnRoles option can be used to filter pages based on the current user's roles.
import {pages} from "@tinloof/sanity-studio";
export default defineConfig({
// ... other Sanity Studio config
plugins: [
pages({
// Presentation's configuration
previewUrl: {
previewMode: {
enable: "/api/draft",
},
},
filterBasedOnRoles: [
{role: "all", filter: "!(_id match 'singleton*')"},
{role: "contributor", filter: "_type == 'blog.post'"},
],
}),
],
});This allows you to build upon the base filter, pathname.current != null, to filter pages based on the current user's roles.
Setting role: "all" will set the filter to all roles while anything else will filter based on the current user's roles.
Support documents without a locale
By default, when internationalization is enabled, only pages whose locale field matches the currently selected locale will be shown in the list. If you have page types that are not translated but you still want them to show up in the list, you can set the requireLocale option to false in your i18n config:
const i18nConfig = {
locales: [
{id: "en", title: "English"},
{id: "fr", title: "French"},
],
defaultLocaleId: "en",
requireLocale: false,
};Now all documents with a pathname field will show up in the list regardless of the filtered locale, even if they don't have a locale field (or their locale is null).
Lock folder renaming
By default, folders can be renamed. Set the folder.canUnlock option to false to disable this.
import {definePathname} from "@tinloof/sanity-studio";
export default defineType({
type: "document",
name: "modularPage",
fields: [
definePathname({
name: "pathname",
options: {
folder: {
canUnlock: false,
},
},
}),
],
});Customizing pages previews
Documents can have their preview customized on the pages navigator using the List Previews API:
export default {
name: "movie",
type: "document",
fields: [
{
title: "Title",
name: "title",
type: "string",
},
{
type: "image",
name: "image",
title: "Image",
},
],
// Preview information
preview: {
select: {
title: "title",
media: "image",
},
prepare({title, image}) {
return {
title,
media: image,
};
},
},
};Customizing folders
By default, folders will have a folder icon and use the pathname/prefix capitalized as the title. You can customize this for individual folders using the folders config option on the plugin:
export default defineConfig({
// ... other Sanity Studio config
plugins: [
pages({
previewUrl: {
previewMode: {
enable: "/api/draft",
},
},
folders: {
"/news": {
title: "Articles",
icon: NewspaperIcon,
},
},
}),
],
});Automatically navigate on pathname change
By default, the pathname field comes with a "Preview" button which is used to navigate to the page within the Presentation iframe when the pathname changes. You can optionally disable this manual button and have the Presentation tool automatically navigate to the new pathname as it changes:
import {definePathname} from "@tinloof/sanity-studio";
export default defineType({
type: "document",
name: "modularPage",
fields: [
definePathname({
name: "pathname",
options: {
autoNavigate: true,
},
}),
],
});The Presentation tool will now automatically navigate to the new pathname as the user types, with a 1 second debounce.
Using the Page Abstract
The Pages Navigator plugin provides a reusable page abstract type that can be extended by your page documents. This abstract includes common page fields like SEO and pathname configuration.
Important: This feature requires the @tinloof/sanity-extends package to be installed and configured:
import {withExtends} from "@tinloof/sanity-extends";
import {defineConfig} from "sanity";
export default defineConfig({
schema: {
types: withExtends([
// Your schema types here
]),
},
});The page abstract is automatically injected by the Pages Navigator plugin and includes:
- SEO fields (meta title, description, og:image)
- Pathname field with i18n support
- Content and settings field groups
You can extend from it in your documents:
import {defineType} from "sanity";
export default defineType({
type: "document",
name: "landingPage",
title: "Landing Page",
extends: "page", // Extend from the page abstract
fields: [
// Add your custom fields here
{
name: "hero",
type: "object",
group: "content",
fields: [
{name: "title", type: "string"},
{name: "subtitle", type: "text"},
],
},
],
});Disabling the Page Abstract
If you don't want to use the page abstract, you can disable it in the plugin configuration:
import {pages} from "@tinloof/sanity-studio";
export default defineConfig({
plugins: [
pages({
abstracts: false, // Disable the page abstract
previewUrl: {
previewMode: {
enable: "/api/draft",
},
},
}),
],
});You can also selectively enable/disable it:
pages({
abstracts: {
page: false, // Specifically disable the page abstract
},
// ... other configuration
})When using the page abstract:
- Your document automatically gets pathname and SEO fields
- The pathname field respects i18n configuration from the plugin
- Fields are organized into content and settings groups
- All Pages Navigator features work seamlessly
Sections
The defineSection field lets you easily define a new section schema. Used in combination with the SectionsArrayInput component, it will render a useful section picker in your Sanity documents.
1. Create a new section schema
// @/sanity/schemas/sections/banner.tsx
export const bannerSection = defineSection({
name: "block.banner",
title: "Banner",
type: "object",
options: {
variants: [
{
/**
* Will be used to display a preview image
* when opening the section picker
*/
assetUrl: "/images/blocks/hero.png",
},
],
},
fields: [
defineField({
name: "bannerSection",
type: "string",
}),
],
});2. Create a sections list array
// @/sanity/schemas/sections/index.tsx
import {bannerSection} from "@/sanity/schemas/sections/banner";
export const sections = [bannerSection];3. Add a section picker to your document
Here, the SectionsArrayInput component is used to render a useful section picker in your Sanity documents.
// @/sanity/schemas/sections/index.tsx
import { sections } = "@/sanity/schemas/sections/index";
import { SectionsArrayInput } from "@tinloof/sanity-studio";
export default defineType({
name: "page",
type: "document",
// ... other fields
fields: [
defineField({
name: 'sectionPicker',
title: 'Section Picker',
type: 'array',
of: sections.map((section) => ({
type: section.name,
})),
components: {
input: SectionsArrayInput,
},
}),
]
})
export const sections = [bannerSection];4. Add sections to your Sanity schema
// @/sanity/schemas/index.tsx
import {sections} from "@sanity/schemas/index";
import page from "@/sanity/schemas/page";
const schemas = [page, ...sections];
export default schemas;documentI18n (DEPRECATED)
⚠️ DEPRECATED: This plugin has been moved to a separate package
@tinloof/sanity-document-i18nwith enhanced features and better template management. Please migrate to the new package.
The documentI18n plugin is an opinionated thin wrapper around Sanity's Document Internationalization that makes it possible to add internationalization without having to specify schema types.
documentI18n enables internationalization on any schema with a locale field.
Migration:
npm install @tinloof/sanity-document-i18n// OLD (deprecated)
import {documentI18n} from "@tinloof/sanity-studio";
// NEW (recommended)
import {documentI18n} from "@tinloof/sanity-document-i18n";
export default defineConfig({
plugins: [
documentI18n({
locales: [
{id: "en", title: "English"},
{id: "fr", title: "French"},
],
}),
],
});See the @tinloof/sanity-document-i18n documentation for complete usage instructions.
localizedItem
The localizedItem utility helps create localized document lists in your Sanity Studio's structure. It creates a nested list structure that groups documents by locale, with an "All" option to view all documents regardless of locale.
Basic usage
import { localizedItem } from '@tinloof/sanity-studio';
import { StructureResolver } from 'sanity/structure';
import { BookIcon } from '@sanity/icons';
const locales = [
{ id: 'en', title: 'English' },
{ id: 'fr', title: 'French' },
];
export const structure: StructureResolver = (S) => {
return S.list()
.title('Content')
.items([
localizedItem(S, 'blog.post', 'Blog posts', locales, BookIcon),
]);Parameters
S: The Sanity Structure Builder instancename: The document type name (string)title: The display title for the list (string)locales: An array of locale objects withidandtitlepropertiesicon: (Optional) Icon to show instead of the default Sanity folder icon to assist with readability
Example with additional locale properties
You can include additional properties
const locales = [
{id: "en", title: "English", countryCode: "US", isDefault: true},
{id: "fr", title: "French", countryCode: "FR"},
];
localizedItem(S, "blog.post", "Blog posts", locales, BookIcon);The utility will create a nested structure with:
- A top-level item with the provided title
- An "All" option showing all documents of the specified type
- Individual locale options that filter documents by their
localefield
singletonListItem
The singletonListItem utility helps create singleton document list items in your Sanity Studio's structure. This is useful for documents that should only have one instance, such as site settings, home pages, or global configuration documents.
Basic usage
import {singletonListItem} from "@tinloof/sanity-studio";
import {StructureResolver} from "sanity/structure";
import {HomeIcon, CogIcon} from "@sanity/icons";
export const structure: StructureResolver = (S) => {
return S.list()
.title("Content")
.items([
singletonListItem(S, "home", "Home Page"),
singletonListItem(S, "settings", "Site Settings"),
// Other list items...
]);
};Parameters
S: The Sanity Structure Builder instancetype: The document type name (string)title: The display title for the singleton document (string)
What it does
The singletonListItem utility creates a list item that:
- Links directly to a single document of the specified type
- Displays the document in form view only (no list view)
- Uses the provided title as the document title in the interface
- Automatically handles the document creation if it doesn't exist
This is particularly useful for documents like:
- Site settings and configuration
- Home page content
- Global navigation
Schemas
iconSchema
Builds upon a string field with an options list to show a preview of the icon select as well as other options.
Basic usage
import {iconSchema} from "@tinloof/sanity-studio";
import {defineType} from "sanity";
export default defineType({
type: "document",
name: "page",
fields: [
{
type: "string",
name: "title",
},
{
...iconSchema,
options: {
list: [
{title: "Calendar", value: "calendar"},
{title: "Chat", value: "chat"},
{title: "Clock", value: "clock"},
],
path: "/icons/select",
backgroundColor: "black",
},
},
],
});Parameters
options.list: Uses the default string option list type of{title: string, value: string}[]options.path: Path where icons are locatedoptions.backgroundColor: Color value to plug into the CSS stylebackgroundColor. Read here for possible values.
redirectsSchema
The redirectsSchema field provides a convenient way to manage URL redirects in your Sanity Studio. It includes a searchable interface to filter redirects by source or destination URLs.
Basic usage
import {redirectsSchema} from "@tinloof/sanity-studio";
export default defineType({
type: "document",
name: "settings",
fields: [
redirectsSchema,
// ... other fields
],
});Features
- Search functionality: Filter redirects by source or destination URL
- Permanent vs temporary redirects: Toggle between permanent and temporary redirects
- Visual preview: Shows redirect type (permanent/temporary) and destination in the list view
- Required validation: Both source and destination fields are required
Field structure
Each redirect object contains:
source(string, required): The original URL pathdestination(string, required): The target URL to redirect topermanent(boolean, required): Whether the redirect is permanent or temporary
Preview
The redirects are displayed in a list format with:
- Title: Shows the source URL
- Subtitle: Shows the destination URL
- Media: Displays the redirect status code
Disable creation plugin
Plugin to disable the creation of documents with the disableCreation option set to true. The plugin does this by:
- limiting the document's action to (these options can be overridden):
- publish
- restore
- discard changes
- removing document type from create button found on the top left of the Studio
Basic usage
sanity.config.ts;
import {disableCreation} from "@tinloof/sanity-studio";
import schemas from "@/sanity/schemas";
export default defineConfig({
name: "studio",
title: "Studio",
projectId: "12345678",
dataset: "production",
schema: {
types: schemas,
},
plugins: [disableCreation({schemas: ["home", "header", "footer"]})],
});Parameters
schemas: String array of document typesoverrideDocumentActions: The document actions to override, defaults to publish, discardChanges, restore
Important notice
When using this plugin, make sure you are placing it after the structureTool().
plugins: [
structureTool(),
visionTool(),
disableCreation({
schemaTypes: schemaTypes as SchemaTypeDefinition[],
}),
],Input with characters count
This is a custom component which shows a characters count below a string input. Requires you to specify the minimum and maximum length of the string in order to render and also show tone states.
Basic usage
Add as a input under components and include the options minLength and maxLength.
{
type: 'object',
name: 'seo',
fields: [
{
type: 'string',
name: 'title',
components: {
input: InputWithCharacterCount,
},
options: {
maxLength: 100,
minLength: 10,
},
},
],
},Parameters
minLength: Number, minimum length of stringmaxLength: Number, maximum length of string
Examples
Check the /examples folder.
License
MIT © Tinloof
Develop & test
This plugin uses @sanity/plugin-kit with default configuration for build & watch scripts.
See Testing a plugin in Sanity Studio on how to run this plugin with hot reload in the studio.
