---
description: Draggable in-point and out-point handles for trimming media element duration directly on the composition timeline.
---
# ef-trim-handles
## Attributes
- **mode** (string, default: standalone) - Layout mode ("standalone" or "track")
- **element-id** (string) - ID of element being trimmed (included in events)
- **pixels-per-ms** (number) - Zoom level for pixel-to-time conversion
- **value** (TrimValue) - Current trim value ({startMs, endMs})
- **intrinsic-duration-ms** (number) - Total duration of source media
- **show-overlays** (boolean, default: true) - Show darkened overlay on trimmed regions
- **seek-target** (string) - ID of element to seek when trimming
# TrimHandles
Interactive trim handles for adjusting the start and end points of media elements. Provides visual feedback and emits events for timeline integration.
## Import
```tsx
import { TrimHandles } from "@editframe/react";
```
## Basic Usage
Trim handles on a video element.
```html live
);
};
```
## With Timeline
Trim handles are automatically enabled in `ef-timeline` when `enable-trim` is set.
```html
```
The timeline handles trim events internally and updates element attributes.
TrimHandles are automatically included when trim mode is enabled:
```tsx
import { Timeline, Timegroup, Video } from "@editframe/react";
```
## Track Mode
In track mode, handles are pinned to container edges for timeline integration.
```html live
Track mode (handles at edges):
```
Handles pinned to track edges:
```tsx
import { TrimHandles } from "@editframe/react";
```
## Standalone Mode
Handles positioned inline with trim values:
```tsx
```
## Hide Overlays
Show handles without dimmed regions:
```tsx
```
## With Seek Target
Automatically seek video when dragging:
```tsx
import { useState } from "react";
import { TrimHandles, Video } from "@editframe/react";
export const SeekingTrimExample = () => {
const [trim, setTrim] = useState({ startMs: 0, endMs: 0 });
return (
setTrim(e.detail.value)}
/>
);
};
```
## Trim Both Ends
Adjust start and end simultaneously:
```tsx
import { useState } from "react";
import { TrimHandles } from "@editframe/react";
export const DualTrimExample = () => {
const [trim, setTrim] = useState({ startMs: 2000, endMs: 3000 });
return (
Trimmed: {trim.startMs}ms to {10000 - trim.endMs}ms
setTrim(e.detail.value)}
/>
);
};
```
## Region Dragging
In standalone mode, drag the region between handles to slide the trim window.
```html live
Drag region to slide trim window:
```
Drag the region between handles to move both:
```tsx
import { useState } from "react";
import { TrimHandles } from "@editframe/react";
export const RegionDragExample = () => {
const [trim, setTrim] = useState({ startMs: 2000, endMs: 2000 });
const handleTrimChange = (e: CustomEvent) => {
console.log("Trim type:", e.detail.type); // "start", "end", or "region"
setTrim(e.detail.value);
};
return (
);
};
```
## Custom Styling
Style handle appearance with CSS custom properties.
```html live
Custom styled handles:
```
Customize handle appearance:
```tsx
```
## Trim Modes
**Standalone mode** (`mode="standalone"`, default):
- Handles positioned absolutely based on trim values
- Shows draggable region between handles
- Best for full-width trim UI
**Track mode** (`mode="track"`):
- Handles pinned to container edges
- No draggable region
- Best for timeline track integration
## Event Handling
### trim-change Event
Fired continuously during drag operations.
```typescript
interface TrimChangeDetail {
elementId: string; // Element being trimmed
type: 'start' | 'end' | 'region'; // Which handle/region moved
value: { // New trim values
startMs: number;
endMs: number;
};
}
```
### trim-change-end Event
Fired when drag completes (on pointer up).
```typescript
interface TrimChangeEndDetail {
elementId: string;
type: 'start' | 'end' | 'region';
}
```
Handle trim events:
```tsx
import { useState } from "react";
import { TrimHandles } from "@editframe/react";
export const TrimEventsExample = () => {
const [trim, setTrim] = useState({ startMs: 0, endMs: 0 });
const [isDragging, setIsDragging] = useState(false);
return (
);
};
```
## Trim Value Semantics
Trim values represent time trimmed from source media:
- `startMs` — Time trimmed from start
- `endMs` — Time trimmed from end
- Effective duration = `intrinsicDurationMs - startMs - endMs`
Example with 10 second source:
- `{startMs: 2000, endMs: 3000}` = play seconds 2-7 (5 second duration)
- `{startMs: 0, endMs: 0}` = play entire source (10 second duration)
## Seeking During Trim
When `seek-target` is set, the element seeks during trim operations:
When `seekTarget` is set, the element seeks during trim operations:
- Dragging start handle — seeks to trimmed start (0:00 of visible region)
- Dragging end handle — seeks to trimmed end (last frame of visible region)
- Dragging region — maintains relative position
## Controlled Trim
Full control over trim state:
```tsx
import { useState } from "react";
import { TrimHandles, Video } from "@editframe/react";
export const ControlledTrimExample = () => {
const [trim, setTrim] = useState({ startMs: 0, endMs: 0 });
const intrinsicDuration = 10000;
const effectiveDuration = intrinsicDuration - trim.startMs - trim.endMs;
return (
```
## CSS Custom Properties
Customize handle appearance:
```css
ef-trim-handles {
--trim-handle-width: 8px;
--trim-handle-color: rgba(255, 255, 255, 0.7);
--trim-handle-active-color: #3b82f6;
--trim-overlay-color: rgba(0, 0, 0, 0.4);
--trim-handle-border-radius-start: 2px 0 0 2px;
--trim-handle-border-radius-end: 0 2px 2px 0;
--trim-selected-border-width: 0px;
--trim-selected-border-color: transparent;
}
```
## Notes
- TrimHandles work in two modes: standalone (inline positioning) or track (pinned to edges)
- Handles constrain dragging to valid ranges
- Region between handles can be dragged to move both simultaneously
- Overlays show trimmed (non-visible) regions
- Use `seek-target` to update video preview while dragging
- Use `seekTarget` to update video preview while dragging
- Event types: "start", "end", or "region" indicate which handle was dragged
- Automatically accounts for zoom level via `pixels-per-ms`
- Automatically accounts for zoom level via `pixelsPerMs`
- CSS custom properties allow extensive styling customization