---
title: "Backdrops"
description: "What a lens refracts, the two kinds of source, and where each one falls short."
canonical_url: "https://liquid-glass.bodbod.ir/docs/guide/backdrops"
---
# Backdrops

> What a lens refracts, the two kinds of source, and where each one falls short.

WebGL can't read the pixels behind a canvas, so every lens needs to be told what to refract. There are two ways to do that.

<table>
<thead>
  <tr>
    <th>
      Source
    </th>
    
    <th>
      Good for
    </th>
    
    <th>
      Cost
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Media: <code>
        :source="imgRef"
      </code>
      
       with an <code>
        <img>
      </code>
      
      , <code>
        <video>
      </code>
      
       or <code>
        <canvas>
      </code>
    </td>
    
    <td>
      Hero sections, cards over photos, video backgrounds
    </td>
    
    <td>
      Very low. Nothing is captured. A video is re-uploaded once per video frame. <code>
        object-fit
      </code>
      
       and <code>
        object-position
      </code>
      
       are respected.
    </td>
  </tr>
  
  <tr>
    <td>
      Snapshot: wrap content in <code>
        <LiquidGlassBackdrop>
      </code>
    </td>
    
    <td>
      Glass over ordinary HTML, like a sticky navbar over page content
    </td>
    
    <td>
      One capture on mount, then again on resize, font load, image load, or when you call <code>
        refresh()
      </code>
      
      . Scrolling never triggers a capture.
    </td>
  </tr>
</tbody>
</table>

If the backdrop is an image or a video, use the media source. A snapshot is a fallback for when it isn't.

```vue
<LiquidGlassBackdrop>
  <LiquidGlass class="sticky top-2 h-14 rounded-2xl">Nav</LiquidGlass>
  <article>…page content…</article>
</LiquidGlassBackdrop>
```

A lens inside a `<LiquidGlassBackdrop>` refracts that snapshot. Snapshots need snapDOM installed and wired up, which [Installation](https://liquid-glass.bodbod.ir/docs/getting-started/installation) covers.

## `<LiquidGlassBackdrop>` props

- `observe`: re-capture when the DOM inside changes (debounced). Off by default.
- `captureScale`: how large the snapshot is relative to the page, `0.5` by default. The blur hides the lower resolution. Raise it, up to `1`, if your lenses magnify or refract text and it looks soft.
- `embedFonts`, `ignoreSaveData`, `capture`.

It exposes `refresh()`.

## Snapshot limitations

<warning>

snapDOM draws your HTML into an SVG `foreignObject` and rasterises that, so a snapshot is never pixel-perfect.

</warning>

- Cross-origin images without CORS headers, iframes and some unusual CSS don't make it into the capture.
- Content that changes constantly, like carousels and counters, needs `observe` or a manual `refresh()`.
- The whole backdrop is a single texture. Its size is capped by the GPU's maximum texture size and by a 16 megapixel canvas limit, so a very tall container is captured at a lower scale than you asked for.

## Cross-origin media

An image or video from another origin has to be CORS-enabled: add `crossorigin="anonymous"` to the element, and make sure the server sends an `Access-Control-Allow-Origin` header. If it doesn't, that lens falls back to CSS and you get one warning in dev mode.


## Sitemap

See the full [sitemap](https://liquid-glass.bodbod.ir/sitemap.md) for all pages.
