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.
1. The block’s own style
Section titled “1. The block’s own style”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
idin the layout, which is rendered as the element’sid - 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:
statandrecord-listrender as a card. Its parts carrydata-slotattributes:card,card-header,card-title,card-description,card-content,card-footer. A stat’s number is thecard-titleand its label is thecard-description.- A
record-listrenders its rows as a plaintablewiththead,th,tbody,trandtd, 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.
Choosing between them
Section titled “Choosing between them”- One supported block, outer element only: use
styleon the block. No custom CSS needed. - A
stat,record-list,data-table,chartorform, or a part inside any block: use the wrapper andcustom_css. - The same look on several blocks: one class through
style.classon 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.
