What you can do
You already opened Maya's homepage hero from Widgets and landed in the composer. Text and Image are on the canvas. A second row under the photo is the wrong place for a stamp that has to sit on the picture.
Two everyday jobs:
- Put a SALE badge on the photo. Add Layer, drop Text in the corner, write the word. The photo stays on the base. The badge lives on Layer 1. Change the wording later without opening the image.
- Set a caption on the hero without stealing the click. The credit sits on the image. In Layer Settings, Pointer Events of none lets the click still hit the hero underneath — the photo's own link or button keeps working.
If the extra content can live in the next row, put it in the next row. Layers earn their keep when the extra content has to occupy the same space as something already there.
| You want | Why a second row will not do | What a layer does |
|---|---|---|
| A sale, new, or featured badge on a product photo | A row under the photo is a caption, not a stamp. Baking the badge into the image means a designer every time the copy changes. | Layer 1 holds a small text or image in the corner. Hide it on phones, or swap the wording, without touching the photo. |
| A caption or credit over a hero | Putting the credit below the hero loses the “on the picture” look the design asked for. | The credit sits on the image. Pointer Events of none lets the hero's own link or button still receive the click. |
| A play, mute, or skip control on a video | A control in the next row is a toolbar, not an overlay. Viewers expect it on the picture. | The control lives on Layer 1, aligned to a corner of the video on the base. |
| A promo or cookie-style strip across a hero that already has a call to action | Another row pushes the hero down. Covering the hero with a normal column steals every click meant for the button underneath. | The strip is a layer. Pointer Events of none on the layer, and auto on the strip's own button, is the usual recipe: decoration passes through, the one control you added still works. |
| A seasonal frame — frost, confetti, a Black Friday banner — on a landing page you do not want to rebuild | Duplicating the whole widget for a two-week campaign doubles the thing you have to keep in sync. | The campaign lives on its own layer. Hide the layer, or delete it, when the season ends. The base is untouched. |
| A device-only treatment — a badge that is fine on desktop and cramped on a phone | Hiding a column on the base also hides the photo it was sitting next to, if you structured it as one piece. | Hide the layer on phones. The base photo stays. Hide Widget in Layer Settings is the control on a widget; on a collection the same drawer names it Hide Collection. The canvas keeps the layer visible so you can still edit it. |
Collections get layers too. A reused card can carry its own “Featured” stamp, and every widget that embeds that collection picks the stamp up after you publish. The authoring is the same — the layer picker sits in the collection header, just left of the gear. See Collections.
How layers think
The widget (or collection) you have always edited is the base. It invents the size of the box. Every overlay layer is another full layout — rows, columns, components, even nested collections — stretched to that same box and painted on top.
The web has always had a name for this third axis: z-index. Later paint wins. Layer 1 sits on the base. Layer 2 sits on Layer 1. There are no custom names in this version, and there is no separate z-index field: the list is the stack.
Here is the case that surprises people. The editing canvas shows one target at a time — Base, or Layer 1, or Layer 2. Layers never paint on top of the thing you are editing. That is deliberate. If they did, you would be clicking through badges to reach the photo underneath. Preview and the published page show the whole stack. Switch the picker back to Base to work on the original layout; the layers disappear from the canvas and wait for Preview.
- A layer is always as wide and as tall as the base. Width and Height in Layer Settings do not change that — the drawer says so. Size the contents of the layer (a small badge, a bottom caption) the way you already size a column.
- The base has to have some height of its own — a photo, a min height, enough content to grow the box. A layer-only widget has nothing to cover.
- Hiding the widget still hides the whole stack, layers included. To hide just the overlay, hide the layer.
Ask AI cannot add, switch, or delete overlay layers. Layers are a separate editing target, not a row you can drop. Use Add Layer in the header. If a layer is already selected, Ask AI will edit that layer's content the same way it edits the base — it will not create the layer for you.
Build your first overlay
You do this after the hero is already on the canvas — the same landing the composer guide already walked. Picture Maya's homepage hero on the Production Default Widget, with Text and Image already there.
- Open the organization → team → project → environment you want to work in. Find the orange Widgets card, View Widgets, then the widget row. Edit Widget opens the composer.
- Look in the header, just left of the settings gear. Click Add Layer. RuleCMS creates an empty layer, selects it, and the canvas switches to that layer so you can start dropping components. The address bar follows along:
?layer=1means Layer 1. - On the left, stay on the Components tab. Drag Text onto the empty layer. Sit it in the corner of the box — that is where the stamp belongs. Type SALE.
- Open the gear. The drawer is now labelled Layer 1 Settings. Find Pointer Events and set it to none. The canvas ignores this so you can still select things. Open Preview to confirm the click still hits the hero.
- Preview shows the composed stack — base, then every layer, in order. That is also what a visitor sees on the published page. Autosave already stored the base plus the layer. That is a safe stop.
Once at least one layer exists, Add Layer becomes a dropdown. Choose Base, Layer 1, Layer 2, and so on, or Add Layer at the bottom to append another. With a layer selected — not Base — a Delete Layer button appears to the right of the dropdown. It removes that layer completely. There is no confirm dialog, because Undo in the top bar brings it back — the same as deleting a column.
Reload, the browser Back button, and a trip into an embedded collection all return you to that layer instead of dropping you on the base. Back to widget (and Back to a parent collection) does the same — it opens the parent on the layer you left, not on Base.
Save and publish always send the whole document. Autosave, Preview, and Publish store the base plus every layer, even while you are editing Layer 2. You will not accidentally publish a badge as if it were the widget. See Publishing.
When you reach for it
With a layer selected, the gear still opens the settings drawer — Layer 1 Settings (or Layer 2, and so on). The controls are the same family as Widget Settings, and they apply to that layer's own box. Two do most of the work:
- Pointer Events — auto (the default) takes the click. none lets the click fall through to the base, which is what a decorative overlay needs. A button you drop on that layer can take clicks back by setting Pointer Events to auto on its own column.
- Hide Widget — or Hide Collection when you are on a collection. Hide this layer on phones, tablets, or desktops. The layer stays on the canvas so you can keep editing it.
Background Color, Opacity, and Typography on the layer are useful for a tint or a default type style. Width and Height on the layer itself do not change the cover — the layer is already 100% of the base.
- Prefer Pointer Events over Hide when the overlay should stay visible. Hide removes the layer from view; none keeps it visible and lets clicks through.
- Deleting a middle layer renumbers the ones above it. Delete Layer 1 and the old Layer 2 becomes Layer 1. Paint order is whatever is left in the list.
- Every setting still has its own page. The information icon in Layer Settings opens the same Attribute Reference as Widget Settings, including Pointer Events.
What to read next
This page is the story and the first walkthrough. The palette, the published snapshot, and the reused card live on the pages below.
- The Composer — The palette, the canvas, and the Modify drawer. Add Layer lives in the header; this page is the rest of that path.
- Ask AI — The same composer operations in ordinary language. It cannot add, switch, or delete overlay layers. If a layer is already selected, it will edit that layer's content.
- RuleCMS Components — Text, Image, Video, and the rest you drop onto a layer.
- Attribute Reference — Every column, row, widget, and collection setting, including Pointer Events and Hide Widget.
- Collections — Shared versus embedded blocks. A reused card can carry its own layers.
- Publishing — Getting a finished draft — base plus every layer — onto staging or production.
How this fits
An overlay layer does not replace the widget. It is another layout painted on the one you already built. The base is still the page. The layer is the stamp, the caption, the seasonal frame. Preview and the published page show both. The canvas shows one at a time so you can edit either without the other getting in the way.
Ask AI is another way to edit the selected target's rows — not a way to add a layer. Publishing is still a later, explicit step. Collections use the same header picker; a Featured stamp on a shared card travels with that collection after you publish it.