Docs

Visual Editor Events

Technical reference for client-side events that Stackbit emits to customize how your site reloads content.

Event Response

When event listener functions fire, they are passed an event object argument with a detail property.

This detail property will contain context for the current editing environment (more on context below), along with custom properties related to the specific event.

  • 1
  • 2
  • 3
window.addEventListener(EVENT_NAME, (event) => {
  // `event.detail` contains all necessary information
})

Event Context

The event.detail object contains contextual properties that are consistent among all events. These properties are detailed in the Context type below.

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
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
}

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.

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
{
  "currentUrl": "...",
  "currentPageObject": {
    "srcObjectId": "...",
    "srcType": "...",
    "srcProjectId": "..."
  },
  "currentPageObjectId": "...",
  "visibleObjectIds": ["...", "...", "..."],
  "visibleObjects": [
    { "srcObjectId": "...", "srcType": "...", "srcProjectId": "..." },
    { "srcObjectId": "...", "srcType": "...", "srcProjectId": "..." },
    { "srcObjectId": "...", "srcType": "...", "srcProjectId": "..." }
  ]
}

Event Listeners

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

stackbitObjectsChanged

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

Usage:

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

To handle this event yourself and disable the default page refresh behavior, make sure to call event.preventDefault() in your callback code - just like you would with standard DOM events.

Event Detail:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
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:

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

Event Detail:

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

Visual Editor Actions

A stackbit object is attached to the window and contains function properties that can be used to customize the visual editing experience.

setLocale

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

Usage:

  • 1
window.stackbit.setLocale(locale)

Parameters:

locale
String that should match the content source's desired locale, which is typically configured in the content source.

This can only be used to update the locale when the current mode is not global.