# OpenCut Video Editor Timeline Component Structure: Current State and Planned Architecture

> Explore the planned architecture for the OpenCut video editor timeline component. Discover how the upcoming structure will leverage UI primitives and a dedicated directory for efficient video editing.

- Repository: [OpenCut.app/OpenCut](https://github.com/OpenCut-app/OpenCut)
- Tags: architecture
- Published: 2026-07-01

---

**The OpenCut video editor timeline component does not exist in the current codebase yet, as the application is being rewritten from the ground up, but the planned structure will likely follow the existing UI primitive patterns in `apps/web/src/components/ui/` and utilize a dedicated `apps/web/src/components/editor/timeline/` directory.**

The OpenCut repository represents a complete rewrite of the video editor, with the current `main` branch containing only foundational UI primitives rather than full editor features. While the timeline functionality remains on the implementation roadmap according to the project README, analyzing the existing component architecture reveals clear conventions that will govern how the video editor timeline component structure is organized when development reaches that milestone.

## Current State of the Timeline Component

The OpenCut source tree currently **does not contain** a concrete timeline UI component. A comprehensive search across the repository for "timeline" only returns matches in non-code files like [`.github/SECURITY.md`](https://github.com/OpenCut-app/OpenCut/blob/main/.github/SECURITY.md), confirming the absence of this feature in the present codebase.

According to the **Status** section of the [`README.md`](https://github.com/OpenCut-app/OpenCut/blob/main/README.md), the project is actively being rewritten with planned features including an Editor API and first-class third-party plugin support. The UI library currently provides only generic primitives—such as [`sidebar.tsx`](https://github.com/OpenCut-app/OpenCut/blob/main/sidebar.tsx), [`tooltip.tsx`](https://github.com/OpenCut-app/OpenCut/blob/main/tooltip.tsx), [`button.tsx`](https://github.com/OpenCut-app/OpenCut/blob/main/button.tsx), and [`slider.tsx`](https://github.com/OpenCut-app/OpenCut/blob/main/slider.tsx)—located in `apps/web/src/components/ui/`. These components are built on top of `@base-ui/react` and serve as the low-level building blocks for future editor-specific interfaces.

## Expected Video Editor Timeline Component Structure

Based on the established patterns in the existing UI architecture, the timeline implementation will likely adhere to a hierarchical component structure organized under a dedicated editor directory.

### Directory Layout and File Organization

When the timeline component arrives, expect the following directory structure to emerge alongside the existing UI primitives:

```

apps/web/
└─ src/
   ├─ components/
   │  ├─ ui/                # Low-level building blocks (existing)

   │  └─ editor/            # Editor-specific UI (future)

   │     └─ timeline/
   │        ├─ Timeline.tsx          # Root component rendering track rows

   │        ├─ Track.tsx             # Individual video/audio track

   │        ├─ Clip.tsx              # Draggable clip blocks

   │        ├─ Playhead.tsx          # Moving playback cursor

   │        ├─ TimelineControls.tsx  # Zoom, snap, and add-track buttons

   │        └─ TimelineProvider.tsx  # Context provider for timeline state

   └─ lib/
      └─ utils.ts           # Tailwind class merging utilities

```

### Component Hierarchy and Data Flow

The video editor timeline component structure will implement a nested composition pattern where **Timeline** renders multiple **Track** components, each hosting **Clip** components representing media segments.

Following the pattern established by `SidebarProvider` in [`apps/web/src/components/ui/sidebar.tsx`](https://github.com/OpenCut-app/OpenCut/blob/main/apps/web/src/components/ui/sidebar.tsx), the timeline will likely utilize a `TimelineProvider` context to supply project timeline data to nested tracks and clips. This approach enables centralized state management for clip positions, zoom levels, and current selection without excessive prop drilling.

State management will likely leverage **React state** or a global store such as Zustand or Recoil to handle complex interactions like drag-and-drop positioning, playhead scrubbing, and multi-track synchronization.

### Technical Implementation Conventions

Components in the timeline directory will import UI primitives from `@base-ui/react`, mirroring the existing sidebar implementation. Each file will utilize the `cn` helper function imported from `#/lib/utils.ts` for Tailwind CSS class composition and conditional styling.

Keyboard shortcuts will follow the pattern seen in `SidebarProvider`, potentially supporting combinations like `Ctrl+←/→` to nudge the playhead or `Delete` to remove selected clips. The architecture will likely leverage `mergeProps` and the `useRender` helper from the existing utility patterns to ensure consistent behavior across interactive elements.

## Key Files to Monitor for Timeline Development

When implementation begins, watch for these specific files in the repository:

| Expected File | Purpose | Import Path |
|---------------|---------|-------------|
| [`Timeline.tsx`](https://github.com/OpenCut-app/OpenCut/blob/main/Timeline.tsx) | Main canvas rendering tracks and playhead | `#components/editor/timeline/Timeline.tsx` |
| [`Track.tsx`](https://github.com/OpenCut-app/OpenCut/blob/main/Track.tsx) | Row component for video/audio/subtitle layers | `#components/editor/timeline/Track.tsx` |
| [`Clip.tsx`](https://github.com/OpenCut-app/OpenCut/blob/main/Clip.tsx) | Draggable and resizable media block | `#components/editor/timeline/Clip.tsx` |
| [`Playhead.tsx`](https://github.com/OpenCut-app/OpenCut/blob/main/Playhead.tsx) | Vertical playback position indicator | `#components/editor/timeline/Playhead.tsx` |
| [`TimelineProvider.tsx`](https://github.com/OpenCut-app/OpenCut/blob/main/TimelineProvider.tsx) | Context wrapper exposing timeline state | `#components/editor/timeline/TimelineProvider.tsx` |

## How to Verify Timeline Implementation Progress

To determine when the video editor timeline component structure becomes available in the codebase:

1. **Search for component files** using terms like [`Timeline.tsx`](https://github.com/OpenCut-app/OpenCut/blob/main/Timeline.tsx) or [`Track.tsx`](https://github.com/OpenCut-app/OpenCut/blob/main/Track.tsx) in the repository root.
2. **Monitor the `apps/web/src/components/editor/`** directory, as this is the anticipated location for all editor-specific UI components.
3. **Check for new imports** from `@base-ui/react` or `react-resizable-panels` (used elsewhere for draggable interfaces) in recent commits.
4. **Review the `apps/web/src/routes/`** directory for timeline-specific route definitions that would indicate functional UI integration.

Until these files appear, contributors can prepare by studying the patterns in [`apps/web/src/components/ui/sidebar.tsx`](https://github.com/OpenCut-app/OpenCut/blob/main/apps/web/src/components/ui/sidebar.tsx) and utilizing the `cn` utility from [`apps/web/src/lib/utils.ts`](https://github.com/OpenCut-app/OpenCut/blob/main/apps/web/src/lib/utils.ts) to ensure compatibility with the existing design system.

## Summary

- The OpenCut video editor timeline component does not currently exist in the `main` branch, as the project is undergoing a complete ground-up rewrite.
- Current UI primitives in `apps/web/src/components/ui/` provide the foundation, utilizing `@base-ui/react` and Tailwind CSS with the `cn` helper from [`apps/web/src/lib/utils.ts`](https://github.com/OpenCut-app/OpenCut/blob/main/apps/web/src/lib/utils.ts).
- The anticipated timeline structure will reside in `apps/web/src/components/editor/timeline/` with a component hierarchy of Timeline > Track > Clip.
- Implementation will likely feature a `TimelineProvider` context for state management and follow keyboard shortcut patterns established in the sidebar component.
- Contributors should monitor the `components/editor/` directory for the appearance of [`Timeline.tsx`](https://github.com/OpenCut-app/OpenCut/blob/main/Timeline.tsx), [`Track.tsx`](https://github.com/OpenCut-app/OpenCut/blob/main/Track.tsx), and [`Clip.tsx`](https://github.com/OpenCut-app/OpenCut/blob/main/Clip.tsx) files to track development progress.

## Frequently Asked Questions

### Is the timeline component available in OpenCut yet?

No, the timeline component is not available in the current OpenCut codebase. The repository contains only foundational UI primitives like buttons, sliders, and sidebars under `apps/web/src/components/ui/`, while the timeline remains on the implementation roadmap according to the project README.

### Where will the OpenCut video editor timeline component be located when implemented?

When implemented, the timeline component will likely reside in `apps/web/src/components/editor/timeline/`, following the convention where `apps/web/src/components/ui/` contains generic primitives and `apps/web/src/components/editor/` houses higher-level editor-specific compositions.

### What UI library does OpenCut use for its component architecture?

OpenCut builds its UI components on top of **@base-ui/react**, a low-level headless component library. This is evident in existing files like [`sidebar.tsx`](https://github.com/OpenCut-app/OpenCut/blob/main/sidebar.tsx) and [`tooltip.tsx`](https://github.com/OpenCut-app/OpenCut/blob/main/tooltip.tsx), which import primitives from this library and utilize the `cn` helper function from [`apps/web/src/lib/utils.ts`](https://github.com/OpenCut-app/OpenCut/blob/main/apps/web/src/lib/utils.ts) for Tailwind class merging.

### How can I contribute to the timeline implementation in OpenCut?

To contribute, create the `apps/web/src/components/editor/timeline/` directory and implement components following the existing patterns: import primitives from `@base-ui/react`, use the `cn` utility for styling, implement a context provider for state management similar to `SidebarProvider`, and ensure keyboard accessibility matches the shortcuts defined in the sidebar component.