Skip to content
pagecraft

CSS Framework

Audience: Site Builder.

The CSS Framework setting tells PageCraft which framework your content is written in. It is not permission for ContentBox to manage your grid.

Set it under Add-Ons → PageCraft → Global Settings → CSS Framework, or override it per field on the field's settings (leave a field on "Use global setting" to inherit).

The short version: building from PageCraft's own blocks? Leave it on Native. Working with imported Bootstrap or Tailwind templates? Set it to match — that is now the right answer, and it used to be the wrong one.

The three options

Setting What you get Use when
Native (default) ContentBox's own .column grid, with its full structural tooling — add/remove rows and columns, drag to resize. You build pages from PageCraft's bundled blocks.
Bootstrap A framework profile: ContentBox never touches layout, structural tools are hidden, and a tailored stylesheet stops its CSS competing with Bootstrap's. Your sections come from an imported Bootstrap template.
Tailwind CSS The same, for Tailwind — plus the bundled Tailwind build so generated classes always resolve. Your sections are authored in Tailwind.

Most sites are all-in on one of these. The setting is designed for that.

What a framework profile actually does

Three things, together:

1. ContentBox stops managing the grid. It switches to a mode where it builds new rows and cells from your framework's classes and never rewrites markup that already exists. Your responsive ladder is safe permanently — not by convention, but because the code path that rewrote it is switched off.

2. Structural tools are hidden. No row add/remove, no column tool, no drag-to-resize. On an imported template the grid is a code concern: if you need a different column split, change the classes in the section's HTML. Everything else stays — the element toolbar, the side panel, and every content panel.

3. A tailored stylesheet is served. This is the part that fixes the styling conflicts, and it is worth knowing why it exists.

Why the tailored stylesheet exists

ContentBox's own utility classes are Tailwind. Its stylesheets define gap-4: 1rem, mb-3: 0.75rem, p-4: 1rem, border-2: 2px, w-full: 100%, flex-col: column — Tailwind's exact scale, from a compiled Tailwind subset baked into the bundle.

On a Bootstrap site those class names collide and the values do not match. Bootstrap's px-4 is 1.5rem; ContentBox's is 1rem. Wherever ContentBox marked its version !important, it won, and your template's spacing quietly changed.

The Bootstrap and Tailwind profiles serve the same stylesheets with !important removed from the ~148 rules whose class names belong to the host framework. Nothing is deleted and no value is rewritten — ContentBox's value still applies wherever your framework defines nothing, and your framework wins wherever it does.

What you give up

Drag-to-resize on framework columns. In ContentBox, column resizing and the layout rewriting are the same mechanism — you cannot have one without the other. The profile turns that mechanism off, so resizing a column means editing its classes. That is the deliberate trade: a grid that never changes underneath you, in exchange for a control that was damaging the thing it edited.

Native is unaffected and keeps full resizing.

Changing an existing site

Switching a field from Native to a framework profile does not convert anything — no markup is rewritten in either direction. The setting only changes what the editor is allowed to do from that point on, so it is safe to try and safe to switch back.

Imported sections do not need re-ingesting after a change.

Tailwind note: Tailwind builds purge unused utility classes, so a class the editor generates may not exist in your compiled CSS. The Tailwind profile loads PageCraft's bundled full Tailwind build so generated grids always resolve.

How it relates to the grid-compat CSS

PageCraft also ships a small Bootstrap grid-compatibility stylesheet (ThemeAssets::gridCompatCss) that keeps imported col-* / row-cols-* grids laying out correctly. It counters a class-name collision on .row, which ContentBox's runtime CSS also claims.

That stylesheet applies on both the front end and the editor canvas, and regardless of this setting — it is scoped by :has() to rows that really do contain Bootstrap column tokens, so it never touches native ContentBox sections. You don't configure it, and the profile does not replace it; the two solve different problems.

Reference

  • Setting storage: framework key in exp_pagecraft_settings (global) / field settings (per-field)
  • Resolution: Traits/ThemeAssets.php::resolveFrameworkProfile() — the single resolver for every surface
  • Editor options: Traits/ThemeAssets.php::frameworkOptsJs()
  • Structural lock: Traits/ThemeAssets.php::frameworkStructureLockCss()
  • Profile stylesheets: generated by scripts/build-css-profiles.py, committed alongside the stock sheets
  • Compat CSS: Traits/ThemeAssets.php::gridCompatCss() — canvas and front end alike