---
title: "Configuration"
description: "Every blueprint property for the Live Preview section – sticky pinning, label, dimensions, and update behavior."
canonical_url: "https://kirby.tools/docs/live-preview/configuration"
---

# Configuration

> Every blueprint property for the Live Preview section – sticky pinning, label, dimensions, and update behavior.

## Section Properties

### `label` <u-badge className="align-middle,ml-2,rounded-full!" label="String" variant="subtle"></u-badge>

The `label` property defines a custom label for the Live Preview section. The default value depends on the Panel language. For English, the default label is `Live Preview`.

To set a custom label, use the `label` property in your blueprint:

```yaml [sections/live-preview.yml]
type: preview
label: Real-Time Preview
```

### `pageId` <u-badge className="align-middle,ml-2,rounded-full!" label="String" variant="subtle"></u-badge>

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:

```yaml [sections/live-preview.yml]
type: preview
pageId: about
```

### `updateStrategy` <u-badge className="align-middle,ml-2,rounded-full!" label="String" variant="subtle"></u-badge>

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 500 milliseconds (0.5 seconds). You can adjust the update interval using the `updateInterval` property.
- `blur`: The preview is updated when any element in the Panel loses focus and the content changed since the last render. Use it when rerendering while the editor types is too expensive.

To change the default strategy to `blur`, use the `updateStrategy` property:

```yaml [sections/live-preview.yml]
type: preview
updateStrategy: blur
```

### `updateInterval` <u-badge className="align-middle,ml-2,rounded-full!" label="Number | Boolean" variant="subtle"></u-badge>

<note>

`updateInterval` throttles both strategies, and switching it off stops one trigger among several. The preview still renders when the section loads, when the Panel language changes, when the page title is edited, when files are sorted, and – with `updateStrategy: blur` – on blur.

</note>

The `updateInterval` property allows you to set the frequency at which the preview is updated. By default, the preview is updated every 500 milliseconds (0.5 seconds). You can adjust the update interval to a custom value in milliseconds (minimum 250ms):

```yaml [sections/live-preview.yml]
type: preview
updateInterval: 1000
```

To stop the preview from following your typing, set the `updateInterval` property to `false`:

```yaml [sections/live-preview.yml]
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` <u-badge className="align-middle,ml-2,rounded-full!" label="Boolean" variant="subtle"></u-badge>

Enabled by default – editors can click links and buttons inside the preview. Set it to `false` and the plugin injects `pointer-events: none` into the rendered page, making the preview inert.

To disable pointer events and prevent the user from interacting with the preview iframe, set the `interactable` property to false:

```yaml [sections/live-preview.yml]
type: preview
interactable: false
```

<note>

During preview refreshes, the pointer events are automatically disabled to prevent the user from interacting with the preview iframe while the content is being updated.

</note>

### `aspectRatio` <u-badge className="align-middle,ml-2,rounded-full!" label="String" variant="subtle"></u-badge>

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:

```yaml [sections/live-preview.yml]
type: preview
aspectRatio: 16/9
```

### `help` <u-badge className="align-middle,ml-2,rounded-full!" label="String" variant="subtle"></u-badge>

Like most other Kirby fields and sections, you can define a help text for the Live Preview section. The text is displayed below the preview window and supports Kirbytext formatting.

```yaml [sections/live-preview.yml]
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.
```

---

Every page of this site as Markdown: <https://kirby.tools/sitemap.md>