Page Custom CSS (Store Editor Advanced panel)
Add your own CSS to a whole page, the header or the footer from the Advanced panel in the Store Editor, read the editor's CSS warnings, reset to the applied template's CSS, and fix CSS that does not show on the store.
Every page in the new Store Editor, plus the header and the footer, has an Advanced panel at the bottom of the right-hand inspector with one box: Custom CSS. Use it for small design touches the visual controls do not cover. The CSS belongs to that one page (or to the header or the footer), so CSS on Cart does not change Checkout.
This is different from the per-section Custom CSS box, which takes declarations only and applies to a single section. See Custom CSS: declarations only for that one. The page-level box described here accepts full rules with selectors.
What you can do
- Write page-wide CSS: variables, attribute selectors that start with
data-, plain element selectors, and@media,@supports,@container,@layer,@keyframesand@font-faceblocks. - See advisory warnings under the box while you type. Warnings never block saving.
- Put back the CSS the applied store template shipped for this page with Reset to template.
Add custom CSS to a page
Screen: Online Store → Store Editor → page switcher → pick the page (or Header or Footer) → inspector on the right → Advanced → Custom CSS.
Open the page
Open the Store Editor and choose the page from the page switcher, for example Cart, Product Detail, Login, Header or Footer.
Find the Advanced panel
Scroll to the bottom of the inspector. The Advanced section is open by default; click its title to collapse or expand it. It appears whether or not a section is selected.
Write your CSS in the Custom CSS box
The box is a monospaced multi-line field. The helper line under it reads: "Use CSS variables first, then stable data attributes. Page CSS is separate from individual section CSS."
Check warnings, preview, publish
Any warnings appear under the helper line (next section). The canvas preview updates as you type. The CSS is part of the page draft and reaches your live store only when you publish the page.
Clearing the box removes the CSS for that page once the draft is saved and published.
Recommended: CSS variables and data-bb-part hooks
The box's own helper line says to use CSS variables first, then stable data attributes. Class names inside the storefront are internal and can change in a release, so a rule built on them may silently stop matching.
- CSS variables. Set a variable and every element that reads it follows. The storefront exposes variables such as
--bb-color-primary,--bb-font-headingand--bb-font-body. A rule that starts with:rootis scoped to the page, so it changes the variable for that page only. data-bb-parthooks. Many storefront designs mark their main parts with a stabledata-bb-partattribute, for exampleheader.navLink,footer.link,plp.gridorcheckout.sidebar. Select it with an attribute selector. Not every part of every design has a hook yet, and a hook only exists on the designs that carry it, so a selector that matches nothing is simply ignored.
An example for the Header page:
:root {
--bb-color-primary: #1d4ed8;
}
[data-bb-part="header.navLink"] {
letter-spacing: 0.06em;
text-transform: uppercase;
}
To find a hook on your own store, open the published page in your browser, right-click the part, choose Inspect, and look for a data-bb-part attribute on it or on a parent. If there is none, use a variable or an element selector scoped to the page instead.
What the editor warns about
When your CSS breaks the template guidelines, a status block appears under the helper line. It starts with "These template CSS guidelines are advisory for your edits. Saving is still available." and then lists one line per problem. Warnings do not block saving or publishing. They tell you which rules are risky or may be removed.
| Warning wording | What triggers it |
|---|---|
| class selectors are not allowed, followed by the start of the rule | A selector with a class, such as a rule starting with a dot and a name. Class names inside the storefront can change between releases. Attribute selectors inside square brackets are not flagged. |
| id selectors are not allowed, followed by the start of the rule | A selector containing a hash id. |
| @import is not allowed | An @import rule. |
| expression()/behavior is not allowed | expression( or a behavior: property. |
| script URLs are not allowed | javascript: or vbscript: anywhere in the CSS. |
| only data:image/ URLs are allowed | A url(...) that uses a data: URL that is not an image. |
| HTML characters are not allowed | A < character outside strings and url values. |
| CSS escape sequences are not allowed outside strings | A backslash outside a quoted string. |
| unterminated comment, unmatched closing brace, unclosed block | Unbalanced comments or braces. |
| followed by "is not allowed" for the at-rule name | Any at-rule other than the six listed above. |
| customCss exceeds 20000 characters | More than 20,000 characters. |
Write curly braces and angle brackets exactly as CSS requires; the editor only warns, it never rewrites what you typed.
Reset to template
Under the warnings, the Reset to template button replaces the box with the CSS that your applied store template ships for this page (or for the header, the footer or the landing page). It becomes a draft change like any other edit; publish to make it live.
The button is disabled, with a one-line reason under it, in three cases:
- "Loading template CSS…" while the applied template is still being looked up.
- "Template CSS could not be loaded. Your CSS is kept." when the lookup failed.
- "The applied template has no CSS for this page. Your CSS is kept." when no template is applied, or the applied template carries no CSS for this page.
What happens when you apply a store template
Applying a store template replaces a page's Custom CSS only when the template carries its own CSS for that page. If the template has none for a page, the CSS you already wrote on it is kept. If you later want the template's version back after editing, use Reset to template.
How the CSS is applied on the storefront
The storefront wraps each page (and the header and footer) that has saved CSS in a marker element carrying data-bb-page with the page's type, and adds your CSS in a style element marked data-bb-custom-css. Before it is added, every rule is scoped to that page:
- A normal selector is prefixed with the page scope, so it can only match elements inside that page.
- A selector that starts with
:root,htmlorbodyis rewritten to target the page scope itself, so page-level custom properties (variables) set there apply to everything on that page. - Loose declarations with no selector are wrapped into one rule on the page scope.
- Animation names in
@keyframesare renamed per page so two pages cannot clash. - Rules and properties the storefront does not accept are removed:
@import, at-rules other than@media,@supports,@container,@layer,@keyframesand@font-face,behavior,expression(, script URLs and non-imagedata:URLs. Markup in the CSS is stripped. - Only the first 20,000 characters are used.
- If the CSS cannot be parsed at all, none of it is applied and the page renders normally.
Class selectors are scoped and still apply on the storefront today, but the editor warns about them because the class names inside the storefront are internal and may change. Prefer variables and data- attribute selectors.
Troubleshooting: why doesn't my CSS show?
Check these in order
- It is still a draft. The editor preview shows your CSS before it is live. Publish the page, then reload the storefront.
- Wrong page. CSS is saved per page, header and footer. Check the page switcher shows the page you want. CSS written on Cart does not apply to Checkout.
- A class or id selector. The editor flags these. Class rules may stop matching after a storefront update, and id selectors are flagged too. Rewrite them with a CSS variable or a
data-attribute selector. - A removed rule.
@import, unsupported at-rules,expression(, script URLs and non-imagedata:URLs are dropped on the storefront. A broken or unbalanced block can make the whole CSS fail to parse, in which case none of it applies. Fix every warning under the box. - Past 20,000 characters. Anything after the 20,000th character is ignored.
- A template was applied afterwards. If the template carries CSS for that page it replaces yours. Re-enter your edits afterwards.
- Reset to template is greyed out. Read the line under the button; it says whether the template CSS is loading, failed to load, or does not exist for this page.