---
description: Video thumbnail strip that generates and displays preview frames at regular intervals along the composition timeline.
---
# ef-thumbnail-strip
## Attributes
- **target** (string) (required) - ID of target video or root timegroup element
- **targetElement** (Element) - Direct reference to target element (alternative to target)
- **thumbnail-height** (number, default: 24) - Height of thumbnails in pixels
- **thumbnail-spacing-px** (number, default: 48) - Spacing between thumbnail centers in pixels
- **pixels-per-ms** (number) - Zoom level (overrides timeline context)
- **use-intrinsic-duration** (boolean, default: false) - Use source duration instead of trimmed duration
# ThumbnailStrip
Visual thumbnail strip showing preview frames from video or timegroup elements. Automatically generates and displays thumbnails at regular intervals along the timeline.
## Import
```tsx
import { ThumbnailStrip } from "@editframe/react";
```
## Basic Usage
Thumbnail strip for a video element.
```html live
```
```tsx
import { ThumbnailStrip, Video } from "@editframe/react";
```
## Adjustable Thumbnail Size
Control thumbnail height while maintaining aspect ratio.
```html live
24px height:
48px height:
```
```tsx
```
## Thumbnail Spacing
Control spacing between thumbnails.
```html live
Dense spacing (24px):
Wide spacing (96px):
```
## Timeline Integration
Thumbnails automatically integrate with timeline zoom and scroll.
```html live
Thumbnails automatically appear in video tracks. Zoom in to see more detail.
```
ThumbnailStrip is typically used inside Timeline:
```tsx
import { Timeline, Timegroup, Video } from "@editframe/react";
```
## Timegroup Thumbnails
Generate thumbnails from entire compositions, not just video.
```html live
One
Two
```
## Target Video Element
Generate thumbnails for a specific video:
```tsx
import { ThumbnailStrip, Video } from "@editframe/react";
```
## Target Timegroup
Generate thumbnails for a composition:
```tsx
import { ThumbnailStrip, Timegroup, Video, Text } from "@editframe/react";
Title
```
## Custom Zoom
Control thumbnail density:
For standalone use, provide explicit `pixels-per-ms` attribute.
```tsx
import { useState } from "react";
import { ThumbnailStrip, Video } from "@editframe/react";
export const ZoomableThumbnails = () => {
const [zoom, setZoom] = useState(0.04);
return (
);
};
```
## Intrinsic Duration
By default, thumbnails show the trimmed region of video:
- `trimstart="2s"` means thumbnails start at 2 seconds into source
- Duration matches effective video duration
Set `use-intrinsic-duration` to show entire source file regardless of trim.
Use source video duration instead of trimmed duration:
```tsx
import { ThumbnailStrip, Video } from "@editframe/react";
```
## With Direct Element Reference
Pass element reference directly:
```tsx
import { useRef, useEffect, useState } from "react";
import { ThumbnailStrip, Video } from "@editframe/react";
export const RefBasedThumbnails = () => {
const videoRef = useRef(null);
const [videoElement, setVideoElement] = useState(null);
useEffect(() => {
if (videoRef.current) {
setVideoElement(videoRef.current);
}
}, []);
return (
);
};
```
## Styled Thumbnails
Customize appearance with CSS variables:
```tsx
```
## Features
**Lazy loading** — Only generates thumbnails for visible region as you scroll.
**Viewport virtualization** — Efficiently handles timelines of any length.
**Smart caching** — Caches generated thumbnails and reuses them when possible.
**Adaptive spacing** — Maintains consistent visual spacing at all zoom levels.
**Frame-accurate** — Aligns thumbnails to frame boundaries for precision.
**Video support** — Extracts thumbnails directly from video files.
**Timegroup support** — Renders composition snapshots with all layers.
**Automatic aspect ratio** — Thumbnails match target element dimensions.
## Target Types
**Video elements** (`ef-video`):
**Video elements**:
- Extracts frames directly from video file
- Fast batch extraction
- Respects video trim settings
**Root timegroups** (top-level `ef-timegroup`):
**Root timegroups**:
- Renders entire composition to thumbnails
- Includes all layers (video, text, images)
- Lower resolution rendering for performance
## How It Works
The thumbnail strip uses different strategies based on target type:
**For videos:**
1. Uses `ThumbnailExtractor` for batch frame extraction
2. Decodes video to access raw frames
3. Caches extracted frames for reuse
4. Supports source time translation for trimmed videos
**For timegroups:**
1. Creates off-screen render clone of composition
2. Seeks to each timestamp and captures canvas
3. Generates at low resolution (0.25x scale) for performance
4. Reuses clone for subsequent thumbnail batches
## Thumbnail Positioning
Thumbnails use a stable grid system:
- Grid is anchored in timeline space (not viewport space)
- Scrolls naturally with timeline content
- On zoom, grid snaps to keep thumbnails near viewport edges
- Prevents visual slipping during zoom operations
Spacing between thumbnails is consistent at all zoom levels, but more thumbnails become visible as you zoom in.
## Performance Optimization
**Batch extraction** — Videos extract multiple frames in one pass.
**Viewport culling** — Only renders thumbnails in visible area plus buffer.
**Canvas pooling** — Reuses canvas elements across renders.
**Abort on scroll** — Cancels in-flight captures when viewport changes.
**Nearest neighbor** — Shows nearby cached thumbnails while loading exact frame.
```tsx
{/* Efficiently handles long videos */}
```
## Trimmed Videos
By default, thumbnails show the trimmed region of video:
- `trimstart="2s"` means thumbnails start at 2 seconds into source
- Duration matches effective video duration
Set `use-intrinsic-duration` to show entire source file regardless of trim.
ThumbnailStrip respects video trim settings by default. Use `useIntrinsicDuration` to show the full source file regardless of trim.
## Timeline Context
When used inside a timeline, the strip automatically:
- Reads zoom level from timeline context
- Synchronizes with timeline scroll position
- Updates viewport window as timeline scrolls
- Respects timeline state without explicit binding
For standalone use, provide explicit `pixels-per-ms` attribute.
For standalone use, provide explicit `pixelsPerMs` prop.
## CSS Custom Properties
Customize appearance:
```css
ef-thumbnail-strip {
--ef-thumbnail-gap: 2px;
--ef-color-bg-inset: rgba(100, 100, 100, 0.3);
--ef-color-border-subtle: rgba(150, 150, 150, 0.5);
--ef-color-error: #ef4444;
}
```
## Error States
The component shows error messages for:
- No target specified
- Target element not found
- Invalid target type (must be video or root timegroup)
Example error: "Invalid target: 'ef-text' must be ef-video or root ef-timegroup"
```tsx
{/* No target specified */}
{/* Invalid target type */}
```
## Usage in Timeline
Thumbnails are automatically rendered in video and timegroup tracks when inside `ef-timeline`. The timeline manages thumbnail strip lifecycle and positioning.
For custom track implementations, use `ef-thumbnail-strip` directly and manage zoom/scroll context.
## Multi-Video Timeline
Each video track gets its own thumbnail strip:
```tsx
import { Timeline, Timegroup, Video } from "@editframe/react";
{/* Each video appears as a separate track with thumbnails */}
```
## Notes
- ThumbnailStrip targets either `ef-video` or root `ef-timegroup` elements
- Automatically generates thumbnails for visible viewport area
- Uses efficient batch extraction for videos
- Canvas rendering for timegroups at low resolution
- Thumbnails align to frame boundaries for accuracy
- Spacing adapts to zoom level
- Shows placeholder while thumbnails load
- Cache persists for smooth scrubbing