Skip to content

Restyle one block on a page

Use this when a page works but one part of it looks plain, and the request is to change that part without changing the rest of the site: a bold stat tile, a larger table, one coloured card.

There are two tools, and which one applies depends on the block type.

Every block in a page layout can carry a style object. A class entry becomes a CSS class on the block. Every other entry is written as an inline CSS property on the block’s outer element.

{
"type": "heading",
"content": { "text": "Today's orders", "level": 2 },
"style": { "class": "board-title", "color": "#7a3b00", "font-size": "2.5rem" }
}

Only these block types apply style: badge, button, card, container, dnd-list, heading, image, kbd, markdown, navigation-menu, separator, spinner, text and video. Three of them apply only part of it: card and navigation-menu take the class entry and ignore inline properties, and dnd-list takes inline properties and ignores class. Every other block type ignores style entirely, including stat, record-list, data-table, chart and form. Setting style on one of those saves without an error and changes nothing.

style reaches the block’s outer element only. It cannot restyle a part inside the block, such as a heading inside a card.

2. A wrapper plus the style’s custom CSS

Section titled “2. A wrapper plus the style’s custom CSS”

For a block that ignores style, or to restyle the parts inside a block, wrap it in a container you can select, then write rules for it in the application style’s custom_css (set with create_style or update_style).

Give the container something to be selected by. Either works:

  • its own id in the layout, which is rendered as the element’s id
  • a class through style.class
{
"id": "stat-new-card",
"type": "container",
"style": { "class": "board-tile" },
"children": [
{ "type": "stat", "source": { "model_id": "<orders model_id>", "aggregation": "count", "filters": { "status": "New" } } }
]
}

Then scope every rule by that id or class:

#stat-new-card [data-slot=card] { background-color: #FFD23F !important; }
#stat-new-card [data-slot=card-title] { font-size: 84px !important; font-weight: 700 !important; line-height: 1 !important; }
#stat-new-card [data-slot=card-description] { font-size: 15px !important; letter-spacing: 0.14em; text-transform: uppercase; }
#list-card td { font-size: 20px !important; padding: 18px 8px !important; }
#list-card tbody tr:first-child { background-color: #FFE89A; }

What the rules above rely on:

  • stat and record-list render as a card. Its parts carry data-slot attributes: card, card-header, card-title, card-description, card-content, card-footer. A stat’s number is the card-title and its label is the card-description.
  • A record-list renders its rows as a plain table with thead, th, tbody, tr and td, so ordinary selectors work.
  • The whole page sits inside an element with the class page-renderer.

The style’s custom_css applies to every page that uses the style. A rule scoped by an id or class that exists on one page cannot leak to the others. A rule without that scope restyles every card or table in the application.

If a rule does not take effect, add !important. The built-in classes set most colours, sizes and paddings, and on the application this was verified against most such rules needed it.

Theme-wide colours belong in :root variables in the same CSS (--primary, --background, --card, --border, --radius), not in per-block rules.

  • One supported block, outer element only: use style on the block. No custom CSS needed.
  • A stat, record-list, data-table, chart or form, or a part inside any block: use the wrapper and custom_css.
  • The same look on several blocks: one class through style.class on each wrapper, one set of rules.

After any change, capture the published page with capture_page_screenshot and look at it. A rule that matches nothing fails silently.