remotion-dev/remotion · error · Error

useTimelineSelectionItem must be used inside…

Error message

useTimelineSelectionItem must be used inside TimelineSelectionProvider

What it means

useTimelineSelectionItem registers a Timeline item with the selection system. It reads TimelineRowSelectionContext and throws this error when the context is null, i.e. the hook is not used inside TimelineSelectionProvider.

Solutions

Ensure the item component using the hook renders within <TimelineSelectionProvider>.
In tests, wrap the component with TimelineSelectionProvider in the render helper.
Check for React portals or memo boundaries that break context propagation and move the provider accordingly.
If building a custom item, accept the selection context via props instead of calling the hook outside the provider.

Example fix

// before
render(<MyTimelineItem item={item} />);
// after
render(
  <TimelineSelectionProvider>
    <MyTimelineItem item={item} />
  </TimelineSelectionProvider>
);

Defensive patterns

Strategy: validation

Validate before calling

// ensure provider exists before rendering the item
<TimelineSelectionProvider>{itemComponent}</TimelineSelectionProvider>

Try / catch

try {
  renderItem();
} catch (e) {
  if (e.message.includes('useTimelineSelectionItem must be used inside')) {
    console.warn('Wrap the item in TimelineSelectionProvider');
  } else throw e;
}

Prevention

Wrap isolated Timeline item tests with TimelineSelectionProvider.
Avoid portals that break context ancestry for Timeline items.
Keep custom item renderers under the provider in the component tree.

When it happens

Trigger: Rendering a Timeline item component (via the hook's wrapper props) outside a TimelineSelectionProvider — typically a custom item renderer extracted from the Timeline tree, or a provider removed during refactor.

Common situations: Custom Studio Timeline item components reused elsewhere in Studio; unit-testing a Timeline item in isolation without the provider; conditional rendering that places items in a portal outside the provider.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

AI-assisted analysis of remotion-dev/remotion@46a3a6bf13 (2026-09-18). Data as JSON: /api/errors/5ffab5ace2524b84. Report an issue: GitHub.

Appendix: source

Thrown at packages/studio/src/components/Timeline/TimelineSelection.tsx:1654

		selectionItem,
		useSelectionOrder: true,
	});
};

const useTimelineSelectionItem = <
	TSelectionItem extends TimelineSelection | null,
>({
	revealInInspector,
	selectionItem,
	useSelectionOrder,
}: {
	readonly revealInInspector: boolean;
	readonly selectionItem: TSelectionItem;
	readonly useSelectionOrder: boolean;
}) => {
	const selectionContext = useContext(TimelineRowSelectionContext);
	if (selectionContext === null) {
		throw new Error(
			'useTimelineSelectionItem must be used inside TimelineSelectionProvider',
		);
	}

	const selectableTimelineItemsRef = useContext(SelectableTimelineItemsContext);
	const selectionItemKey = useMemo(
		() =>
			selectionItem === null ? null : getTimelineSelectionKey(selectionItem),
		[selectionItem],
	);
	const getSelectedState = useCallback((): TimelineSelectionState | null => {
		if (selectionItemKey === null) {
			return null;
		}

		const snapshot = selectionContext.getSnapshot();
		return snapshot.selectedItems.some(
			(item) => getTimelineSelectionKey(item) === selectionItemKey,

View on GitHub (pinned to 46a3a6bf13)