Blocks

1. The third template type

Overlabels has three template types. Static overlays are the always-on layer you add to OBS. Alerts fire on events and render inside a static overlay (see Overlays vs Alerts). Blocks are the new third kind: pieces. A block is never added to OBS by itself - it exists to be placed on a grid in the Builder, alongside other blocks, compiling into a full static overlay.

Inside a block, everything you already know works: template tags like [[[follower_count]]], conditionals, formatting pipes, and Controls. A block is a regular template that happens to be small and composable.

2. Creating a block

Two ways in:

• From scratch: Create Overlay and pick the Block card. You get the same editor as every other template.
• From an existing overlay: the Copy action on any static overlay asks whether the copy should be a static overlay or a block. Great for turning a piece of the public library into Builder material.

On the block's Meta tab you set a suggested size: how many grid columns and rows the block occupies when someone places it (they can always resize afterwards). A compact counter might suggest 4x2; a big centerpiece might want 8x4. If the free space at the clicked cell is smaller, the Builder shrinks the placement to fit.

3. Writing block HTML and CSS

When a block is placed, it lives inside a wrapper element that spans its grid cells - a box with a definite width and height. The single most useful pattern for a block is therefore fill the box you're given:

<!-- Body -->
<div class="item">
  [[[follower_count]]] followers
</div>

/* CSS */
.item {
  width: 100%;
  height: 100%;
  display: grid;
  place-content: center;
  background-color: #15803d;
  color: #ffffff;
  font-size: 1.875rem;
}

width: 100%; height: 100% on your root element makes the block fill whatever cell area a user gives it - 2x2 or 8x4, it adapts. Content-sized blocks are fine too; they'll simply sit at their natural size inside their area.

Your CSS is scoped for you

Write plain CSS with whatever class names you like. At compile time, the Builder prefixes every selector to the block's own wrapper, so two blocks both styling .label can never collide. Selectors targeting :root, html, or body are mapped onto the wrapper - so CSS variables you define on :root become variables on your block, private to it:

/* you write */
:root { --accent: #a78bfa; }
.label { color: var(--accent); }

/* the Builder compiles, for a placement with id a3f2 */
#blk-a3f2 { --accent: #a78bfa; }
#blk-a3f2 .label { color: var(--accent); }

4. Controls travel with your block

Add controls to your block exactly as you would on any overlay, and reference them with [[[c:your_key]]]. When someone places your block and saves, the controls it needs are created on their overlay automatically, with your defaults - the block arrives batteries included.

• If a control with the same key already exists on the overlay, it's shared, not duplicated. Blocks that agree on a key stay in sync - deliberate, and worth designing for: a generic key like donation_total invites sharing, a specific one like subathon_end_at keeps to itself.
• Integration-managed controls (Ko-fi, StreamLabs, and friends) are account-wide already and don't travel with blocks - only your own custom controls do.

5. Snapshots: placing copies your code

When someone places your block, the Builder copies your code at that moment into their overlay. From then on, their overlay never references your block again. You can edit your block freely, rename it, even delete it - overlays that placed it keep working, byte for byte, forever.

Updates still flow - just explicitly. When a placed block's source has newer code, the Builder shows a "Source updated" badge on the placement and offers Refresh from source: one click re-takes the snapshot in place, keeping position and size. Renames are even gentler - a block's name is just a label, so placements pick up your new name automatically.

6. Publishing your block

Flip your block to public and it appears in everyone's Builder picker, searchable by name and description. A good public block ships with:

• a clear name and a description that says what it shows and which controls it uses,
• a sensible suggested size,
• fill-the-box CSS (see section 3) so it looks right at any placement size,
• sane control defaults, so it renders something meaningful the moment it's placed.

Private blocks are just as useful - build a personal kit of pieces and recompose your own overlays in minutes instead of hours.