Custom Preview Styles

Sveltia CMS comes with built-in styles for the entry preview pane. However, you can also register your own custom preview styles to make the preview look like your site.

Overview

To register a custom preview style, use the registerPreviewStyle method on the CMS object:

CMS.registerPreviewStyle(filePath);

CMS.registerPreviewStyle(cssString, { raw: true });

There are two ways to register custom preview styles in Sveltia CMS: by providing a file path to a CSS file or by providing a raw CSS string. If you provide a raw CSS string, you need to set the raw option to true.

Parameters

• filePath (string): The path to the CSS file containing the custom styles. This file should be accessible from the CMS admin interface. It can be a relative path, which is resolved against the current page URL, or an absolute URL.
• cssString (string): A string containing the raw CSS styles to be applied to the preview pane.
• options (object, optional): An options object that can contain the following property:
  • raw (boolean): Set this to true if you are providing a raw CSS string. Defaults to false.

Examples

Registering a Preview Style from a File

To register a preview style from a CSS file, simply provide the file path as an argument to the registerPreviewStyle function.

CMS.registerPreviewStyle('/path/to/your/custom-style.css');

Registering a Preview Style from a Raw CSS String

You can also register a preview style by providing a raw CSS string. Make sure to set the raw option to true in the options object.

const customCSS = `
  body {
    background-color: lightgoldenrodyellow;
  }
`;

CMS.registerPreviewStyle(customCSS, { raw: true });

Registering Multiple Preview Styles

You can register multiple preview styles by calling the registerPreviewStyle function multiple times. The styles will be applied in the order they were registered.

CMS.registerPreviewStyle('/path/to/first-style.css');
CMS.registerPreviewStyle('/path/to/second-style.css');

This allows you to layer styles and create complex customizations for the entry preview.

Styling Specific Fields

The default preview marks each field with three attributes that identify it, which your preview styles can use to target specific fields:

• data-field-type: The field’s type, i.e. its widget option, e.g. string, markdown, or the name of a custom field type.
• data-key-path: The field’s key path, e.g. title for a top-level field, details.author for a field in an Object field, or sections.0.heading for a subfield of the first item in a List field.
• data-typed-key-path: The same path with every List item index replaced with an asterisk, so one selector matches the subfield in all the items, e.g. sections.*.heading. For a List or Object field with variable types, the type name follows in angle brackets, e.g. blocks.*<image>.src.

[data-key-path='title'] p {
  font-size: 2em;
}

[data-typed-key-path='sections.*.body'] p {
  font-family: serif;
}

[data-field-type='markdown'] {
  line-height: 1.8;
}

A custom preview template has these attributes only where it adds them itself, apart from the field previews that widgetFor and widgetsFor return.

The fields in the Edit Pane have the same attributes, so you can also style them with CSS on your admin page. The preview is rendered in an iframe once you register a preview style, so your admin page styles don’t affect it, and your preview styles don’t affect the Edit Pane.

The attributes are primarily for internal use, and the rest of the markup, such as class names and element structure, may change in any release, so keep your selectors as simple as possible.

Why “key path”?

The term comes from the IndexedDB API, where a key path is a dot-separated path to a value in an object. Sveltia CMS handles entry data as a flattened object, keyed by these paths, so the term is used throughout the app and its API, e.g. in the fieldsMetaData prop of a custom preview template.

Showcase

Real-world examples of custom preview styles can be found in our showcase.