Preview Events

As content editors interact with various controls in the Netlify Create visual editor, Netlify Create runs a preview of the site to reflect content changes in real time.

By default, the preview server is just your development server, along with an injected JavaScript snippet for communicating with the Netlify Create API. This snippet provides various hooks for customizing the preview experience in response to user actions.

Emitted Events#

Netlify Create fires the events below based on the various triggers from actions taken by content editors in the Netlify Create application.

stackbitObjectsChanged#

Fires when content changed. This event is typically used to override the default automatic content reload behavior.

Usage Example#

window.addEventListener('stackbitObjectsChanged', (event) => {
  // Override default refresh behavior ...
})

Event Object Details#

The event.detail object contains the following unique properties, along with the base-level context properties.

interface ContentChangeDetails extends Context {
  /** A list of all changed objects (see event `Context` for `ObjectDefinition` type details) */
  changedObjects: ObjectDefinition[]
  /** `srcObjectId` for each changed object */
  changedObjectIds: string[]
  /** An array of ID values for affected content types */
  changedContentTypes: string[]
}

stackbitLocaleChanged#

Fires when an editor changes the current locale using the locale switcher.

Usage Example#

window.addEventListener('stackbitLocaleChanged', (event) => {
  const locale = event.detail.locale
  // Add custom behavior ...
})

Event Object Details#

The event.detail object contains the following unique properties, along with the base-level context properties.

interface LocaleChangeDetails extends Context {
  /** The new chosen locale, which will match the value expected and used by the content source */
  locale: string
}

Event Callback Properties#

When event callback fires, the function is called with the standard Event properties, along with a detail property, containing the necessary editing-specific context.

The detail property contains unique properties for the event, as referenced above, along with a set of base-level properties, documented below.

type Context = {
  /** URL path to page active in visual editor */
  currentUrl: string
  /** The page document for the current URL path */
  currentPageObject: ObjectDefinition
  /** Alias for currentPageObject.srcObjectId */
  currentPageObjectId: string
  /** ID values (from CSI module) for all objects visible on the current page */
  visibleObjectIds: string[]
  /** Object details for those visible on the current page */
  visibleObjects: ObjectDefinition[]
}

type ObjectDefinition = {
  /** Object ID from the content source (set by CSI module) */
  srcObjectId: string
  /** Name of the content source type (provided by CSI module) */
  srcType: string
  /** ID for project within the content source (set by CSI module) */
  srcProjectId: string
}

Event Context Example#

Here's an example of an expected shape for the base-level context object, available as event.detail in an event listener callback. Additional custom properties are documented below.

{
  "currentUrl": "...",
  "currentPageObject": {
    "srcObjectId": "...",
    "srcType": "...",
    "srcProjectId": "..."
  },
  "currentPageObjectId": "...",
  "visibleObjectIds": ["...", "...", "..."],
  "visibleObjects": [
    { "srcObjectId": "...", "srcType": "...", "srcProjectId": "..." },
    { "srcObjectId": "...", "srcType": "...", "srcProjectId": "..." },
    { "srcObjectId": "...", "srcType": "...", "srcProjectId": "..." }
  ]
}

Editor Actions#

A stackbit object is attached to the window by the snippet script. It contains properties that can be used to customize the visual editing experience, as documented below.

setLocale#

Switches the current locale. The updated locale will be reflected in the locale switcher.

Usage Example#

window.stackbit.setLocale(locale)

Parameters#

Preview Controls#

The following objects are attached directly to the window object.

stackbitPreviewControls#

Provides the ability to add custom controls to the Netlify Create visual editor. This enables editors to change some context within the preview without adjusting the underlying content.

The property should be set to an array of individual control objects. The options for controls are documented below.

Usage Example#

Here's a brief and incomplete example for the sake of usage. See the feature guide for a more thorough example.

const themeControl: PreviewControl = {
  name: 'theme',
  context: 'global',
  type: 'enum',
  options: ['light', 'dark'],
  value: currentTheme,
  onChange: (value) => setCurrentTheme(value as 'light' | 'dark'),
}

window.stackbitPreviewControls = [themeControl]

Configuration Properties#

Preview control definitions are extensions of field definitions. The field definition specifies how to render the preview control for the user. See the fields reference for the desired field type.

Shared Properties

The control-specific properties are dependent on the context in which the control should be rendered. The shared properties are listed below, followed by unique properties for each context.

Global Context Properties

The global context requires no additional properties.

Field Context Properties

Field contexts require the following additional properties to specify where exactly the control should be rendered.