---
description: "Individual overlay element that tracks a specific composition element, following its position and size during playback."
---
# ef-overlay-item
## Attributes
- **element-id** (string) - Element ID to track (searches data-element-id or data-timegroup-id)
- **target** (string | HTMLElement) - CSS selector or element reference to track
## Methods
- **updatePosition(): void** - Update position based on target element (called by parent layer)
# OverlayItem
Individual overlay that tracks and follows a target element's position.
## Import
```tsx
import { OverlayItem } from "@editframe/react";
import type { OverlayItemProps } from "@editframe/react";
```
## Basic Usage
Track an element with an overlay:
```html live
Selected Box
```
```tsx
import { OverlayLayer, OverlayItem, Timegroup, Video } from "@editframe/react";
export const App = () => {
return (
);
};
```
## Target Selection
Overlay items support multiple ways to specify targets:
### CSS Selector
Use any valid CSS selector:
```html
```
### Element Reference
Pass element directly via JavaScript:
```javascript
const overlay = document.querySelector('ef-overlay-item');
const element = document.getElementById('my-element');
overlay.target = element;
```
### Element ID Attribute
Use element-id for canvas elements with data attributes:
```html
```
### By Element ID
Use `elementId` for Editframe elements with data attributes:
```tsx
```
### Custom Target Selector
```tsx
import { OverlayItem } from "@editframe/react";
export const CustomTarget = () => {
return (
{/* Track by custom selector */}
{/* Track by direct element reference */}
);
};
```
## Overlay Content
Add any content inside the overlay item:
### Selection Border
```html
```
### Labels and Badges
```html live
);
};
```
## Rotation Support
Overlay items automatically track element rotation:
```html live
Rotated Element
```
The overlay automatically rotates to match its target.
Overlay items automatically track element rotation. The overlay rotates to match its target's transform.
## Visibility
Overlay items automatically hide when target is not found:
```javascript
const overlay = document.querySelector('ef-overlay-item');
// Target exists - overlay visible
overlay.target = '#existing-element';
// Target not found - overlay hidden (display: none)
overlay.target = '#nonexistent-element';
// Target removed - overlay hidden
const element = document.getElementById('existing-element');
element.remove();
```
- When `elementId` or `target` resolves to an element, the overlay is visible
- When the target element is not found or removed, the overlay hides automatically
- If the element is re-added to the DOM, the overlay reappears on the next frame
## Pointer Events
Enable pointer events for interactive overlays:
```html
```
Overlay layer has `pointer-events: none`, so explicitly enable on items that need interaction.
Parent OverlayLayer has `pointer-events: none` by default. Enable pointer events on individual items that need interaction by adding appropriate className.
## Coordinate System
Overlay items use absolute positioning relative to their parent overlay layer:
- **x, y**: Top-left position in layer coordinates
- **width, height**: Match target element dimensions
- **rotation**: Parsed from target element's transform
The parent layer handles transform synchronization with pan/zoom.
## Update Frequency
Position updates happen every animation frame (60fps) via the parent layer's RAF loop. No throttling or change detection - updates are always fresh.
## Performance
Overlay items are passive - they don't run their own RAF loops. The parent layer manages all updates in a single synchronized loop, preventing RAF proliferation.
## Target Validation
Overlay items verify target is still in the DOM:
```javascript
const overlay = document.querySelector('ef-overlay-item');
const element = document.getElementById('my-element');
overlay.target = element; // Works - element in DOM
element.remove(); // Element removed
// Overlay automatically hides
document.body.appendChild(element); // Element re-added
// Overlay reappears on next frame
```
## CSS Styling
Style the overlay item container:
```css
ef-overlay-item {
/* Border and background */
border: 2px solid blue;
background: rgba(0, 0, 255, 0.1);
/* Pointer interaction */
pointer-events: auto;
cursor: pointer;
/* Transform origin (rotation center) */
transform-origin: center;
}
```
### Hover State Overlay
```tsx
import { OverlayLayer, OverlayItem } from "@editframe/react";
export const HoverOverlay = () => {
const [hoveredId, setHoveredId] = useState(null);
return (
);
};
```
## Position Change Event
The `position-changed` event provides:
The `onPositionChanged` callback receives an event with this detail structure:
```typescript
interface OverlayItemPosition {
x: number; // Left position relative to OverlayLayer
y: number; // Top position relative to OverlayLayer
width: number; // Element width
height: number; // Element height
rotation: number; // Element rotation in degrees
}
```
## Important Notes
- Must be a child of an ef-overlay-layer element
- Updates position continuously in sync with parent's RAF loop
- Automatically handles element rotation transforms
- Hidden when target element is not found
- Position is relative to the overlay layer container
- Use `element-id` for canvas elements with data attributes
- Use `target` for custom DOM elements
- Must be a child of OverlayLayer component
- Updates position continuously in sync with parent's RAF loop
- Automatically handles element rotation transforms
- Hidden when target element is not found
- Position is relative to the OverlayLayer container
- Use `elementId` for Editframe elements with data attributes
- Use `target` prop for custom DOM elements