GlobalsDefining a global

Defining a global

A global is content that exists once and appears on many pages: the header, the footer, the company's contact details. You declare it in code; editors edit it in one place under Globals.

View as Markdown

Two kinds

smoodly.global() takes a name, a title, and exactly one of section or fields:

smoodly/globals.ts
import { f, smoodly } from "smoodly";
import { headerSchema } from "@/components/sections/Header.schema";
import { footerSchema } from "@/components/sections/Footer.schema";
import { quoteSchema } from "@/components/sections/Quote.schema";

export const header = smoodly.global({ name: "header", title: "Header", section: headerSchema, layout: true });

export const footer = smoodly.global({ name: "footer", title: "Footer", section: footerSchema, layout: true });

export const contact = smoodly.global({
  name: "contact",
  title: "Contact details",
  fields: {
    email: f.text(),
    phone: f.text().optional(),
    address: f.text().localized(),
  },
  layout: true,
});

export const quote = smoodly.global({ name: "quote", title: "Quote", section: quoteSchema });

export const globals = [header, footer, contact, quote];
  • A visual global takes a registered section's schema. Its fields, settings and styles are the section's, and it renders through the section's view. The starter's header, footer and quote are visual.
  • An object global takes fields of its own and renders nowhere by itself; your code reads it. The starter's contact details are one, read by the footer.

Register the list in the config's globals. A visual global's section must be in the sections list too, which is why the starter's header and footer sit in smoodly/sections.ts although no zone lists them.

Layout globals

layout: true says a global is part of every page: the header, the footer, the contact details the footer shows. On Astro the page's own read brings every layout global along, so the layout's getLiveEntry calls cost nothing; a page that hides the header simply does not read it. Leave the flag off a global that editors place in zones or that one view reads, such as the starter's quote or a form section used on a few pages: it is resolved into each page that places it, and a view that reads it pays one call. In development, a page render that reads an unflagged global prints a hint naming it, once. On Next the flag changes nothing: its data cache keeps every global until that global is published again.

In the admin

Globals, under ⋮ in the admin's top bar, lists every global with its kind, Visual or Fields, and its status in the selected language. A Fields global opens a form like an entry's, the fields in schema order. A Visual global opens on a canvas: a page of the site that shows it, the home page for a layout global and otherwise the first page that places it, with the global selected and the rest of the page dimmed. Its fields sit beside the canvas under Content and Settings, text marked for inline editing can be typed in place, and when several pages place it, Shown on picks the page. A visual global no page shows yet opens as a form. Either way the page autosaves, and carries the same Publish control, History and Discard changes as a page.

A global exists in every language from the start, so there is nothing to add or delete. Publishing is per language, as for pages. A field's value is shared across languages unless it chains .localized(): the starter's contact email is one value, its address is translated.

Reading a global

Your code reads a global by name and language, through the reads. It is null until the global is published in that language, so the caller renders nothing rather than an empty header.

A global item is its own live collection, globalLoader(footer) in src/live.config.ts, read with getLiveEntry("footer", { locale }); the value is the entry's data:

src/layouts/Layout.astro
---
// …
const [{ entry: header }, { entry: footer }, { entry: contact }] = await Promise.all([
  getLiveEntry("header", { locale }),
  getLiveEntry("footer", { locale }),
  getLiveEntry("contact", { locale }),
]);
// …
---
// …
    {footer && <Footer {...footer.data.fields} settings={footer.data.settings} styles={footer.data.styles} contact={contact?.data.fields} />}

A global resolves to { locale, fields }, and a visual global adds settings with defaults filled, and styles. Spread fields onto the section's view, with settings and styles beside it, and the section renders with the spacing steps an editor chose and the id the canvas uses to select it.

Placing a global on a page

A visual global can also be placed in a zone. z.locked(quote) binds a zone to it, so every page of that type shows the one quote; in a freeform or sections zone that allows the global's section, the Add section picker offers it under Global. A placed global is a link, not a copy: editing it anywhere changes it everywhere, and the canvas tags it global.

A page cannot be published in a language while a global it shows is unpublished there. Publishing the page does not publish the global; that is a click of its own, in the global's canvas card or on its page.

Next, Header and footer walks through the starter's layout.

Edit this page on GitHubLast updated 14 Nov 2026