Features
Loop Zone Overlay
Add a visual, interactive loop region on top of the timeline with draggable handles.
The LoopZoneOverlay renders a draggable repeat region on top of your <Timeline>. Users can drag the loop boundaries to adjust the loop region interactively.
Live Preview
Setup
LoopZoneOverlay must be mounted as a sibling to <Timeline> inside a position: relative wrapper, and receive the same geometry props (scale, scaleWidth, startLeft) as the <Timeline>.
import React, { useState } from "react";
import { Timeline, LoopZoneOverlay } from "@keplar-404/react-timeline-editor";
export const EditorLoopZone = () => {
const [loopOn, setLoopOn] = useState(true);
const [loopStart, setLoopStart] = useState(2);
const [loopEnd, setLoopEnd] = useState(8);
const [scrollLeft, setScrollLeft] = useState(0);
// These must match between Timeline and LoopZoneOverlay
const scale = 1;
const scaleWidth = 160;
const startLeft = 20;
return (
<div style={{ position: "relative" }}>
<Timeline
scale={scale}
scaleWidth={scaleWidth}
startLeft={startLeft}
editorData={[]}
effects={{}}
onScroll={(p) => setScrollLeft(p.scrollLeft)}
/>
{loopOn && (
<LoopZoneOverlay
scale={scale}
scaleWidth={scaleWidth}
startLeft={startLeft}
scrollLeft={scrollLeft}
loopStart={loopStart}
loopEnd={loopEnd}
onLoopStartChange={setLoopStart}
onLoopEndChange={setLoopEnd}
config={{
bandColor: "#10b981",
bandOpacity: 0.1,
showBoundaryLines: true,
}}
/>
)}
</div>
);
};Configuration (LoopZoneConfig)
| Option | Type | Default | Description |
|---|---|---|---|
bandColor | string | '#10b981' | CSS color for the loop region highlight |
bandOpacity | number | 0.07 | Opacity of the loop highlight (0–1) |
bandBorderColor | string | — | Border/stripe color used on the band's edges and stripe pattern. Falls back to bandColor when not set. |
handleColor | string | — | CSS color of the default drag handle grip pills. Falls back to bandColor when not set. Has no effect when renderHandle is provided. |
showBoundaryLines | boolean | true | Show dashed vertical lines at loop edges |
boundaryLineColor | string | 'rgba(16, 185, 129, 0.4)' | CSS color of the dashed boundary lines. |
Custom Handle Renderer
Replace the default drag handles with your own React nodes:
<LoopZoneOverlay
{/* ...geometry props... */}
loopStart={loopStart}
loopEnd={loopEnd}
onLoopStartChange={setLoopStart}
onLoopEndChange={setLoopEnd}
renderHandle={(side) => (
<div className={`my-handle my-handle-${side}`}>
{side === 'start' ? '⟨' : '⟩'}
</div>
)}
/>Integration with useTimelinePlayer
Combine with the player hook for automatic loop-back behavior:
const player = useTimelinePlayer(timelineRef, {
loop: { enabled: loopOn, start: loopStart, end: loopEnd },
});
// The hook automatically resets playback to loopStart when currentTime >= loopEndSee the full Loop Zone API Reference for all available props.