Background

A directive rune that produces no visible output. Place {% bg %} as the first child of any block rune to add a background layer with images, video, overlays, blur, and positioning controls.

Image background

Add a background image to any rune that supports backgrounds.

{% hint type="note" %}
{% bg src="/images/texture.jpg" %}
Content with a background image.
{% /hint %}

Video background

Use a looping video as the background.

{% hero %}
{% bg video="/videos/loop.mp4" %}
# Welcome
{% /hero %}

Gradient fill

A token-driven gradient is the most common generated backdrop (heroes, CTAs). Set it inline with gradient (direction), from/to (and optional via) — semantic token names, resolved to var(--rf-color-*) so the gradient tracks the theme/tint — and gradient-type (linear default, radial, conic). A gradient raises the bg layer with no image needed.

{% hero %}
{% bg gradient="to-b" from="primary" to="surface" %}
# Gradient hero
A two-stop linear gradient, top to bottom, from token colours.
{% /hero %}

Directions are a bounded set: to-t, to-b, to-l, to-r, to-tr, to-br, to-bl, to-tl (no raw angles — that's the escape hatch's job). These also work as host-level facets (bg-gradient, bg-from/bg-to/bg-via, bg-gradient-type) without a {% bg %} child, and a theme can register a named gradient preset (bg="brand-fade").

Stop shapes

Each gradient stop accepts three forms:

• Token name — from="primary" emits var(--rf-color-primary), theme- and tint-aware.
• transparent — the CSS keyword. from="transparent" to="primary" fades from clear to the theme colour without falling back to a raw-CSS preset.
• name/alpha — Tailwind-style shorthand for a token at partial opacity. to="primary/0.5" (decimal) or to="primary/50" (percent) compiles to color-mix(in srgb, var(--rf-color-primary) 50%, transparent). Useful for soft washes (from="transparent" to="primary/0.3") that still track the theme's primary.

Overlay

A flat colour wash over the background, for legibility. dark / light are presets; a token name (e.g. overlay="primary") washes with var(--rf-color-primary) at overlay-opacity.

{% hero %}
{% bg src="/images/photo.jpg" overlay="dark" %}
# Readable heading
The dark overlay ensures text remains legible over the image.
{% /hero %}

Scrim

A structured legibility treatment behind overlaid text — richer than a flat overlay. scrim sets the heavy edge (top/bottom/left/right); scrim-type is gradient (default, a directional darken/lighten) or frost (a backdrop-filter blur + tint); scrim-tone (dark/light) picks whether it darkens or lightens — and flips the overlaid content's foreground to match, so a dark scrim gives you light text (and light gives dark text) without setting colours by hand.

The scrim* attributes are universal attributes on the rune the background sits behind, not attributes of {% bg %} — bg supplies the image, the rune carries the treatment:

{% hero scrim="bottom" scrim-strength="lg" %}
{% bg src="/images/photo.jpg" %}
# Legible over the photo
A bottom-weighted gradient scrim keeps the heading readable.
{% /hero %}

scrim-strength (sm/md/lg) tunes the gradient; scrim-blur (sm/md/lg) tunes frost. In cover mode the same scrim targets the media well (see card).

Blur

Apply a blur effect to the background image.

{% hint type="note" %}
{% bg src="/images/bg.jpg" blur="sm" %}
Subtle blur softens the background.
{% /hint %}

Position and fit

Control how the background image is positioned and scaled within its container.

{% hint type="note" %}
{% bg src="/images/portrait.jpg" position="top" fit="contain" %}
The image is anchored to the top and scaled to fit without cropping.
{% /hint %}

Fixed background

Create a parallax-style effect where the background stays fixed during scroll.

{% hero %}
{% bg src="/images/landscape.jpg" fixed=true %}
# Parallax Hero
The background stays in place as you scroll.
{% /hero %}

Combined attributes

All attributes can be used together for full control.

{% hero %}
{% bg src="/images/scene.jpg" overlay="dark" blur="lg" position="top" opacity="0.8" %}
# Full Control
Dark overlay, heavy blur, top-aligned, and slightly transparent.
{% /hero %}

Attributes

Named presets & the escape hatch

A theme or project registers named bg presets (applied with bg="name"). A preset's gradient is structured and token-driven:

// refrakt.config.json (project) or theme config → backgrounds
"backgrounds": {
  "brand-fade": { "gradient": { "type": "linear", "direction": "to-br", "stops": ["primary", "surface"] } }
}

For the genuine long tail (animations, exotic effects) a preset may carry a raw-CSS escape hatch, style — a last resort that bypasses the token system (you own cross-theme behaviour and portability):

"backgrounds": {
  "aurora": { "style": { "background": "conic-gradient(/* … hand-tuned … */)" } }
}

Backgrounds are valid in theme config and project config (refrakt.config.json); project backgrounds merge over theme backgrounds by name. A build-time soft warning flags a raw gradient in style that the structured gradient field now covers.