You're reading docs for Nextly Alpha. APIs may change between releases.

Page Builder

Custom CSS

Add your own CSS where the builder's controls stop, for the whole site, one page or one block, checked and scoped before it reaches a page.

Custom CSS is your own CSS, for the cases the builder's style controls don't cover. It can be written for the whole site, for one page or for one block, and it is drawn on the published page and on the canvas.

Custom CSS is experimental: the customCss route option, pageBuilderCustomCss and the checker may change before they are stable.

Show it on your site

A pages route draws custom CSS only through the page builder's checker. Add this line to your pages route (and to any other route that draws page builder pages), or your custom CSS is saved but never shown on the live site:

app/[[...slug]]/page.tsx
import { createBlocksPage } from "@nextlyhq/blocks-react/next";
import { pageBuilderCustomCss } from "@nextlyhq/plugin-page-builder";

import { pageBuilderPlugin } from "../../nextly.config";

export const { ContentPage, generateMetadata } = createBlocksPage({
  collections: ["pages"],
  field: "content",
  customCss: pageBuilderCustomCss({ plugin: pageBuilderPlugin }),
});

plugin is the page builder your nextly.config.ts installs (the value pageBuilder() returned): the route reads the site's CSS through it. Without plugin the route draws the page's and the blocks' CSS, and none for the whole site. A route without customCss draws none of it, at any level. The canvas always draws it, the site's CSS included, through the same checker, so it shows what the live page shows once the route has the line.

Site, page and block CSS

  • The whole site: drawn first, on every page.
  • One page: drawn after the site's, on that page.
  • One block: drawn after the page's, on that block only.

All three come after the builder's own styles, so your CSS wins a tie with them, a page's wins a tie with the site's, and a block's wins a tie with its page's.

The site's CSS

The site's CSS is saved under the site settings permission, by a signed-in person: an API key can never save it, as it can never save site code. The server checks every save with the same checker, and refuses one made while someone else saved theirs: "Someone changed the site CSS; reload to see it". Each save is recorded in the audit log (who saved it, when, how long it is and its SHA-256, never the CSS itself), and every cached published page is refreshed, so the next visitor gets the new CSS.

The site's CSS has no version history yet: a save replaces what was there. Keep a copy if you may want to go back.

Write the site's CSS in Settings

People who may change the site's settings write it in the builder: open the page's settings, then Site settings, and under Code choose Add code (or Edit code). The CSS box sits above Head and End of body, with the line "CSS for every page of the site. Write plain CSS; no <style> tags needed."

Save code checks the CSS first, with the checker below. What it refuses is listed under the box, each line by its number with the reason, and nothing is saved, the code beside it included. Accepted, the CSS is saved, and the note says it applies to every published page at once. The canvas draws it on the page, never on the builder's own panels.

If someone else saved the site's CSS while you were editing, nothing is saved and your CSS stays in the box: save again to replace theirs, or cancel to see what they saved.

People without the site settings permission get no Site settings, so no CSS box.

A page's CSS

A page's CSS is written in the builder, in Page settings → Code, in the CSS box above Head and End of body: "CSS for this page only. Site-wide CSS lives in Site settings." Check and keep CSS checks it with the same checker the server uses, naming each line it refuses, and keeps it with the page. Like the page's code, it is saved in the draft on Save, goes live on Publish, and comes back with an older version you restore. Where the page's field is kept per language, each language keeps its own.

Only people who may change the site's settings see the box. Anyone else sees one line on General, "This page adds its own code or CSS. Only people who can change site settings can edit it; anyone who can edit the page can read it.", and the builder doesn't show them the CSS.

That keeps the builder simple; it isn't a lock on reading. Anyone who may edit the page can read its CSS, and its blocks' CSS: the draft's, the published version's and every version in its history, through the API and in the document the builder loads, whose canvas draws it. The published CSS also reaches every visitor's browser. What the permission guards is changing it, below.

Who may change page and block CSS

The server judges every save of a page, a saved section, a component or a template that adds or changes CSS, whatever the editor checked first:

  • only someone who may change the site's settings may add or change it, and never through an API key. Anyone else's save is refused: "Only people who can change site settings can change custom CSS."
  • what the checker refuses is refused, naming the line, and nothing is saved.

Anyone who may edit the page may still move, duplicate and delete blocks that have CSS, place a saved section whose blocks carry some, and detach a component the page places: that CSS was written, and checked, by someone permitted. Changing its text is a change, and needs the permission.

Copying is not a change either. Someone without the permission may still duplicate a whole page, save blocks as a section and turn them into a component, keeping their CSS, when that CSS is a byte-for-byte copy of what the source holds. The server reads the source as the person copying before it creates the copy, so the CSS counts as copied only from a version and fields that person could read. An API key may copy the same way. CSS the source doesn't hold, or one changed on the way, is new CSS and still needs the permission.

Each change to a document's CSS, its own or its blocks', is recorded in the audit log: hashes and sizes of both, before and after, and which document and field, never the CSS itself.

A block's CSS starts from selector

Write selector where the block goes. Every rule of a block's CSS must start from it:

selector {
  border: 4px solid rebeccapurple;
}
selector:hover {
  border-color: tomato;
}
selector h2 {
  margin: 0;
}
@media (min-width: 40em) {
  selector {
    padding: 2rem;
  }
}

When the page is drawn, selector becomes the block's own selector, so the CSS reaches that block and what is inside it, and nothing else. The block keeps selector as you wrote it, so a copied, moved or exported block, or one saved as a section or a component, still styles itself wherever it lands.

A rule that doesn't start from selector is refused, naming its line, and so is an at-rule that can't be confined to one block, like @font-face or @keyframes. Put those in the page's CSS.

Write a block's CSS in the builder

A block's CSS is written in the builder, in the block's Advanced tab, in its last section, Custom CSS. Only people who may change the site's settings, the permission that guards site code, see that section. It stays folded until you open it, even when the block has CSS; a dot beside its name says it holds some.

Type your CSS in the box, writing selector for the block. When you leave the box or press Apply, the CSS is checked: CSS the checker accepts is applied to the block on the canvas at once, as one step that Undo takes back. If it refuses anything, each refused line is listed under the box with its reason ("Line 3: @import isn't allowed."), and nothing is applied until you fix it. Emptying the box removes the block's CSS.

Everyone who edits the page can see that a block has custom CSS, but not what it says:

  • its row in Layers shows a { } mark, named "Has custom CSS";
  • the top of its Style tab says "This block also has custom CSS". For someone who may change it, Edit opens Advanced at the box; anyone else is told it was set by someone who can change site code.

The Style tab never holds CSS of its own. Find a setting finds the section by "Custom CSS", "CSS" or "code", and Only changed counts a block's CSS as one of its settings.

Someone without the permission can still move, copy or delete a block that has custom CSS: a copy keeps the CSS, and deleting the block removes it with the block.

What the checker refuses

The same checker runs in the admin and on the server, so they never disagree. It refuses, naming the line:

  • @import;
  • any url(…) that isn't a path on your site (url(/images/a.png) is fine; https://, //, data: and javascript: addresses are not);
  • anything that would end the style element early (</style), and a pasted <style> wrapper: "Leave out the <style> tags". What is inside the tags is still checked, so every refusal is named at once;
  • what can run script in a browser that still honours it: expression(), behavior and -moz-binding;
  • CSS longer than 50,000 characters.

Custom CSS that is refused is not saved. A value already stored that the checker refuses, from an import or an older version say, is kept but not drawn anywhere.