---
description: "Container that positions overlay items absolutely over a composition, anchoring them to their target elements during playback."
---
# ef-overlay-layer
## Attributes
- **panZoomTransform** ({ x: number, y: number, scale: number }) - Pan/zoom transform (fallback when context unavailable)
## Methods
- **registerOverlayItem(item: EFOverlayItem): void** - Register an overlay item for coordinated updates
- **unregisterOverlayItem(item: EFOverlayItem): void** - Unregister an overlay item
# OverlayLayer
Container for positioned overlays that track element positions in a canvas or composition.
## Import
```tsx
import { OverlayLayer } from "@editframe/react";
```
## Basic Usage
Overlay layer provides a coordinate system for overlays:
```html live
);
};
```
## With Pan/Zoom
Overlay layer automatically syncs with ef-pan-zoom transforms:
```html live
Element 1
Element 2
```
Pan and zoom the canvas - overlays stay perfectly positioned on their targets.
```tsx
import { PanZoom, OverlayLayer, OverlayItem } from "@editframe/react";
export const ZoomableEditor = () => {
return (
{/* OverlayLayer automatically syncs with PanZoom transform */}
Title Text
);
};
```
## Architecture
Overlay layer runs a single RAF loop that:
1. Reads the current pan/zoom transform
2. Applies transform to the layer container
3. Updates all registered overlay items
4. Schedules next frame
This ensures all overlays update synchronously without individual RAF loops.
## Transform Context
Overlay layer consumes pan/zoom transform from context when nested inside ef-pan-zoom:
```html
```
For sibling relationships, overlay layer reads transform directly from the DOM:
```html
```
OverlayLayer automatically discovers and syncs with PanZoom transforms via Lit context. When placed inside a PanZoom component, no manual transform wiring is needed.
## Fallback Transform
Provide transform as property for testing or standalone usage:
```javascript
const overlayLayer = document.querySelector('ef-overlay-layer');
overlayLayer.panZoomTransform = { x: 0, y: 0, scale: 1 };
```
## Coordinate System
Overlay layer creates a coordinate space that:
- Matches the transformed canvas position
- Allows overlay items to use absolute positioning
- Updates every frame via RAF loop
- Supports pointer events through `pointer-events: auto` on overlay items
## Registration
Overlay items auto-register with their parent layer:
```javascript
// Registration happens automatically in connectedCallback
const item = document.createElement('ef-overlay-item');
item.target = '#my-element';
overlayLayer.appendChild(item); // Item registers itself
// Unregistration happens in disconnectedCallback
item.remove(); // Item unregisters itself
```
Manual registration is possible but not required:
```javascript
const overlayLayer = document.querySelector('ef-overlay-layer');
const overlayItem = document.querySelector('ef-overlay-item');
overlayLayer.registerOverlayItem(overlayItem);
// Later...
overlayLayer.unregisterOverlayItem(overlayItem);
```
## Pointer Events
Overlay layer has `pointer-events: none` by default. Enable pointer events on individual items:
```html
```
OverlayLayer has `pointer-events: none` by default. Child elements should set `pointer-events: auto` to receive interactions.
## With Transform Handles
```tsx
import { OverlayLayer, OverlayItem, TransformHandles } from "@editframe/react";
export const Editor = () => {
const [bounds, setBounds] = useState({ x: 100, y: 100, width: 400, height: 300 });
return (
);
};
```
## Custom Overlay Styling
```tsx
import { OverlayLayer, OverlayItem } from "@editframe/react";
export const StyledOverlays = () => {
return (
{/* Dashed border overlay */}
{/* Gradient border overlay */}
{/* Shadow overlay */}
);
};
```
## Performance
Single RAF loop ensures:
- No RAF proliferation (one loop for all overlays)
- No change detection overhead
- No delay between transform and overlay updates
- Synchronized updates across all overlay items
## Positioning
Overlay layer uses `position: absolute` and `inset: 0` to fill its container:
```html
```
OverlayLayer must be positioned with `position: absolute` or `fixed` to properly overlay content.
## Transform Origin
Overlay layer uses `transform-origin: 0 0` to match canvas transform behavior.
## Architecture Notes
- OverlayLayer runs a single RAF loop that updates all child OverlayItems synchronously
- Automatically discovers and syncs with PanZoom transforms via Lit context
- Overlays track element positions in real-time using `getBoundingClientRect()`
- No change detection - updates happen every frame for smooth tracking
- Child elements should set `pointer-events: auto` to receive interactions
## Important Notes
- Must be positioned with `position: absolute` or `fixed`
- Use with ef-overlay-item children to track specific elements
- Automatically handles pan/zoom transforms when inside ef-pan-zoom
- Updates continuously - no manual refresh needed
- All overlay items update in sync to prevent visual glitches
- Must be positioned with `position: absolute` or `fixed`
- Use with OverlayItem children to track specific elements
- Automatically handles pan/zoom transforms when inside PanZoom
- Updates continuously - no manual refresh needed
- All OverlayItems update in sync to prevent visual glitches