Skip to main content

Site Settings Schema

Complete reference documentation for the Site Settings document schema in Sanity CMS.

Overview​

The Site Settings document contains global configuration for the website, including contact information, social links, and site-wide settings.

Document Type​

Type Name: siteSettings
Document Type: Singleton (single document instance)

Fields​

Type: image
Required: No
Description: Site logo image

Type: object
Required: No
Description: Social media profile links

Sub-fields:

  • facebook (string, optional) - Facebook page URL
  • twitter (string, optional) - Twitter profile URL
  • linkedin (string, optional) - LinkedIn profile URL
  • instagram (string, optional) - Instagram profile URL
  • github (string, optional) - GitHub profile URL

Contact Information​

Phone Numbers​

The Site Settings document supports multiple phone numbers with location-based display.

Fields:

  • contactPhones (array, optional) - Array of phone number objects
  • contactPhone (string, optional, legacy) - Single phone number for backward compatibility

Phone Number Object Structure:

  • number (string, required) - The phone number (e.g., "+1 234 567 8900")
  • label (object, optional) - Localized label for the phone number
    • en (string, optional) - English label
    • es (string, optional) - Spanish label
    • ro (string, optional) - Romanian label
  • displayLocation (array, required) - Where the phone number should be displayed
    • Options: "contact" (Contact Page), "footer" (Footer)
    • Can select one or both locations

Example:

{
  "contactPhones": [
    {
      "number": "+1 234 567 8900",
      "label": {
        "en": "Main",
        "es": "Principal",
        "ro": "Principal"
      },
      "displayLocation": ["contact", "footer"]
    },
    {
      "number": "+1 234 567 8901",
      "label": {
        "en": "Sales",
        "es": "Ventas",
        "ro": "Vânzări"
      },
      "displayLocation": ["contact"]
    },
    {
      "number": "+1 234 567 8902",
      "label": {
        "en": "Support",
        "es": "Soporte",
        "ro": "Suport"
      },
      "displayLocation": ["footer"]
    }
  ]
}

Migration Notes:

  • The legacy contactPhone field is still supported for backward compatibility
  • New implementations should use the contactPhones array
  • Frontend code should check contactPhones first, then fall back to contactPhone

Email​

Type: string
Required: No
Description: Primary contact email address

Address​

Type: object
Required: No
Description: Physical business address

Sub-fields:

  • street (string, optional)
  • city (string, optional)
  • state (string, optional)
  • zipCode (string, optional)
  • country (string, optional)

Business Hours​

Type: object
Required: No
Description: Business operating hours

Sub-fields:

  • monday (string, optional)
  • tuesday (string, optional)
  • wednesday (string, optional)
  • thursday (string, optional)
  • friday (string, optional)
  • saturday (string, optional)
  • sunday (string, optional)

Sanity Schema Definition​

{
  name: 'siteSettings',
  type: 'document',
  title: 'Site Settings',
  // Singleton pattern
  __experimental_actions: [
    'create',
    'update',
    'publish',
    'delete'
  ],
  fields: [
    {
      name: 'logo',
      type: 'image',
      title: 'Logo',
      options: {
        hotspot: true
      }
    },
    {
      name: 'socialLinks',
      type: 'object',
      title: 'Social Links',
      fields: [
        { name: 'facebook', type: 'url', title: 'Facebook' },
        { name: 'twitter', type: 'url', title: 'Twitter' },
        { name: 'linkedin', type: 'url', title: 'LinkedIn' },
        { name: 'instagram', type: 'url', title: 'Instagram' },
        { name: 'github', type: 'url', title: 'GitHub' }
      ]
    },
    {
      name: 'contactPhones',
      type: 'array',
      title: 'Contact Phone Numbers',
      description: 'Multiple phone numbers with location-based display',
      of: [{
        type: 'object',
        fields: [
          {
            name: 'number',
            type: 'string',
            title: 'Phone Number',
            validation: Rule => Rule.required()
          },
          {
            name: 'label',
            type: 'object',
            title: 'Label',
            fields: [
              { name: 'en', type: 'string', title: 'English' },
              { name: 'es', type: 'string', title: 'Spanish' },
              { name: 'ro', type: 'string', title: 'Romanian' }
            ]
          },
          {
            name: 'displayLocation',
            type: 'array',
            title: 'Display Location',
            of: [{ type: 'string' }],
            options: {
              list: [
                { title: 'Contact Page', value: 'contact' },
                { title: 'Footer', value: 'footer' }
              ]
            },
            validation: Rule => Rule.required().min(1)
          }
        ],
        preview: {
          select: {
            number: 'number',
            label: 'label.en',
            locations: 'displayLocation'
          },
          prepare({ number, label, locations }) {
            return {
              title: label ? `${label}: ${number}` : number,
              subtitle: locations?.join(', ') || ''
            }
          }
        }
      }]
    },
    {
      name: 'contactPhone',
      type: 'string',
      title: 'Contact Phone (Legacy)',
      description: 'Legacy single phone number. Use contactPhones array for new implementations.'
    },
    {
      name: 'contactEmail',
      type: 'string',
      title: 'Contact Email'
    },
    {
      name: 'address',
      type: 'object',
      title: 'Address',
      fields: [
        { name: 'street', type: 'string' },
        { name: 'city', type: 'string' },
        { name: 'state', type: 'string' },
        { name: 'zipCode', type: 'string' },
        { name: 'country', type: 'string' }
      ]
    },
    {
      name: 'businessHours',
      type: 'object',
      title: 'Business Hours',
      fields: [
        { name: 'monday', type: 'string' },
        { name: 'tuesday', type: 'string' },
        { name: 'wednesday', type: 'string' },
        { name: 'thursday', type: 'string' },
        { name: 'friday', type: 'string' },
        { name: 'saturday', type: 'string' },
        { name: 'sunday', type: 'string' }
      ]
    }
  ],
  preview: {
    prepare() {
      return {
        title: 'Site Settings'
      }
    }
  }
}

GraphQL Query​

query GetSiteSettings {
  SiteSettings(id: "siteSettings") {
    logo {
      asset {
        url
      }
    }
    socialLinks {
      facebook
      twitter
      linkedin
      instagram
      github
    }
    contactPhones {
      number
      label {
        en
        es
        ro
      }
      displayLocation
    }
    contactPhone
    contactEmail
    address {
      street
      city
      state
      zipCode
      country
    }
    businessHours {
      monday
      tuesday
      wednesday
      thursday
      friday
      saturday
      sunday
    }
  }
}

TypeScript Types​

interface ContactPhoneNumber {
  number: string
  label?: {
    en?: string
    es?: string
    ro?: string
  }
  displayLocation: ('contact' | 'footer')[]
}

interface SiteSettings {
  logo?: {
    asset: {
      url: string
    }
  }
  socialLinks?: {
    facebook?: string
    twitter?: string
    linkedin?: string
    instagram?: string
    github?: string
  }
  contactPhones?: ContactPhoneNumber[]
  contactPhone?: string // Legacy
  contactEmail?: string
  address?: {
    street?: string
    city?: string
    state?: string
    zipCode?: string
    country?: string
  }
  businessHours?: {
    monday?: string
    tuesday?: string
    wednesday?: string
    thursday?: string
    friday?: string
    saturday?: string
    sunday?: string
  }
}

Best Practices​

Phone Number Formatting​

  • Use international format: +1 234 567 8900
  • Include country code
  • Use consistent spacing
  • Consider readability for users

Display Locations​

  • Contact Page: Use for primary contact numbers
  • Footer: Use for general contact or support numbers
  • Both: Use for main business numbers that should be visible everywhere

Labels​

  • Keep labels short and descriptive
  • Use consistent naming across languages
  • Common labels: "Main", "Sales", "Support", "Emergency"