Configuration
The Kirby Live Preview plugin enhances the content editing experience by providing a real-time preview of the content as it is being edited. This document describes how to configure the Live Preview section properties to tailor the preview experience to your needs.
Section Properties
label
String
The label
property allows you to define a custom label for the Live Preview section. The default value depends on the language of the Panel. For English, the default label is Live Preview
.
To set a custom label for the Live Preview, use the label
property in your blueprint:
type: preview
label: Real-Time Preview
pageId
String
By default, the Live Preview section displays the current page being edited in the Panel (or the home page if it is being rendered at site level). If you want to preview a different page, you can specify the page ID using the pageId
property. The page ID must be a valid page ID in your Kirby installation.
To preview a specific page with the ID about
, use the pageId
property:
type: preview
pageId: about
updateStrategy
String
The page preview will rerender automatically when new unsaved content is detected. The updateStrategy
property allows you to control how the preview is updated when changes are made to the content. The following update strategies are available:
interval
: The preview is updated at a fixed interval. By default, the preview is updated every 250 milliseconds (0.25 seconds). You can adjust the update interval using theupdateInterval
property.blur
: The preview is updated when any Kirby text-like, number-like, or blocks field loses focus. This is useful when you want to update the preview only when the user has finished typing or editing a field.
To change the default strategy to blur
, use the updateStrategy
property:
type: preview
updateStrategy: blur
updateInterval
Number Boolean
updateStrategy
is set to interval
(default).The updateInterval
property allows you to set the frequency at which the preview is updated. By default, the preview is updated every 250 milliseconds (0.25 seconds). You can adjust the update interval to a custom value in milliseconds:
type: preview
updateInterval: 1000
To disable the automatic preview rendering altogether, set the updateInterval
property to false
:
type: preview
updateInterval: false
This can be useful if you want to manually refresh the preview by clicking the refresh button in the preview toolbar.
interactable
Boolean
This property enables or disables pointer events (mouse or touch) within the rendered preview page. When pointer events are enabled, the user can interact with the preview iframe, such as clicking on links or buttons. When pointer events are disabled, the user cannot interact with the preview iframe. Pointer events are enabled by default.
To disable pointer events and prevent the user from interacting with the preview iframe, set the interactable
property to false:
type: preview
interactable: false
aspectRatio
String
The Live Preview section grows to fit the height of the Panel window. For certain use cases, you may want to set a specific aspect ratio for the preview area. This is useful when you want to simulate the aspect ratio of a specific device or screen size.
The aspect ratio value must be a string formatted as width/height
(e.g., 16/9
). If an invalid aspect ratio is specified, an exception will be thrown.
To set an aspect ratio for the Live Preview, use the aspectRatio
property:
type: preview
aspectRatio: 16/9
help
String
Like most other Kirby fields and sections, you can define a help text for the Live Preview section. This text is displayed below the preview window and can be used to provide additional information or instructions to the user.
type: preview
help: |
The Live Preview section shows a real-time preview of the content as you type. It updates automatically and provides a live rendering of the page content.