Skip to content

πŸŽ₯ Make videos programmatically with React

Elements: Link sidebar categories to catalog sections

Igor Samokhovetsef07bb910178
diff --git a/.agents/skills/scaffold-element/SKILL.md b/.agents/skills/scaffold-element/SKILL.md
index 93d65dd46a..dc3edd56b7 100644
--- a/.agents/skills/scaffold-element/SKILL.md
+++ b/.agents/skills/scaffold-element/SKILL.md
@@ -5,7 +5,7 @@ description: Scaffold a new Remotion Element for development in the docs Remotio
# Scaffold a Remotion Element
-Read the [Element guidelines](../../../packages/docs/elements/guidelines.mdx) for design and implementation guidance and the [Element contribution guide](../../../packages/docs/docs/contributing/elements.mdx) for the official gallery submission process. Then follow its [Develop the Element](../../../packages/docs/docs/contributing/elements.mdx#1-develop-the-element) section.
+Read the [Element guidelines](../../../packages/docs/docs/studio/creating-elements.mdx) for design and implementation guidance and the [Element contribution guide](../../../packages/docs/docs/contributing/elements.mdx) for the official gallery submission process. Then follow its [Develop the Element](../../../packages/docs/docs/contributing/elements.mdx#1-develop-the-element) section.
After scaffolding, suggest opening Docs Studio to preview the Element. If the user agrees, start it without opening a browser automatically:
diff --git a/packages/docs/docs/contributing/elements.mdx b/packages/docs/docs/contributing/elements.mdx
index 775f2f62dc..74cf442034 100644
--- a/packages/docs/docs/contributing/elements.mdx
+++ b/packages/docs/docs/contributing/elements.mdx
@@ -10,7 +10,7 @@ description: Create and submit a Remotion Element for the Elements gallery.
First, [set up the repository](/docs/contributing).
-Use your AI coding agent to build an Element. Give it this page and the [Element guidelines](/elements/guidelines).
+Use your AI coding agent to build an Element. Give it this page and the [Element guidelines](/docs/studio/creating-elements).
## 1. Develop the Element
@@ -21,7 +21,7 @@ Create a dotted paper background Element.
Use the notebook paper Element as a reference.
```
-See the guidelines for [dependencies](/elements/guidelines#dependencies), [assets](/elements/guidelines#assets), and [initial props](/elements/guidelines#initial-props).
+See the guidelines for [dependencies](/docs/studio/creating-elements#dependencies), [assets](/docs/studio/creating-elements#assets), and [initial props](/docs/studio/creating-elements#initial-props).
Open Studio to check the animation:
diff --git a/packages/docs/docs/studio-protocol/component-library-integration.mdx b/packages/docs/docs/studio-protocol/component-library-integration.mdx
index 8ef8caf9e9..1fd5cd26c5 100644
--- a/packages/docs/docs/studio-protocol/component-library-integration.mdx
+++ b/packages/docs/docs/studio-protocol/component-library-integration.mdx
@@ -10,7 +10,7 @@ crumb: '@remotion/studio-protocol'
An Element contains the source code for one component. It also contains the data that Studio needs to insert the component.
Studio writes the source code to an `.element.tsx` file. Studio installs only the packages in the Element's `dependencies` list.
-A component that follows the [Element guidelines](/elements/guidelines) is usually ready for Studio.
+A component that follows the [Element guidelines](/docs/studio/creating-elements) is usually ready for Studio.
Use this procedure to preview and deliver a component:
@@ -109,7 +109,7 @@ When Studio embeds the library through Browse Elements, use [`isInsideStudio()`]
## See also
- [Third-party Element Libraries](/elements/libraries)
-- [Element guidelines](/elements/guidelines)
+- [Element guidelines](/docs/studio/creating-elements)
- [`<Player>`](/docs/player)
- [`createElementPayload()`](/docs/studio-protocol/create-element-payload)
- [`staticFileRef()`](/docs/studio-protocol/static-file-ref)
diff --git a/packages/docs/docs/studio-protocol/create-element-payload.mdx b/packages/docs/docs/studio-protocol/create-element-payload.mdx
index 50e0b5e3aa..a77bf7bd0f 100644
--- a/packages/docs/docs/studio-protocol/create-element-payload.mdx
+++ b/packages/docs/docs/studio-protocol/create-element-payload.mdx
@@ -115,7 +115,7 @@ With `'wrapped'`, Studio generates a [`<Sequence>`](/docs/sequence) around the c
With `'component-owned-sequence'`, Studio puts timing, name, and absolute positioning props on the component call without adding an outer Sequence. The component must provide its own Studio-editable Sequence and rendered dimensions.
-See [Choose an installation mode](/elements/guidelines#choose-an-installation-mode) for guidance on choosing a mode and wiring the component.
+See [Choose an installation mode](/docs/studio/creating-elements#choose-an-installation-mode) for guidance on choosing a mode and wiring the component.
### isCaptionStyle?<AvailableFrom v="4.0.535" />
diff --git a/packages/docs/elements/guidelines.mdx b/packages/docs/docs/studio/creating-elements.mdx
similarity index 82%
rename from packages/docs/elements/guidelines.mdx
rename to packages/docs/docs/studio/creating-elements.mdx
index 785531d041..76018ca7a8 100644
--- a/packages/docs/elements/guidelines.mdx
+++ b/packages/docs/docs/studio/creating-elements.mdx
@@ -1,12 +1,16 @@
---
-title: Element Guidelines
-sidebar_label: Guidelines
+image: /generated/articles-docs-studio-creating-elements.png
+title: Creating Elements
description: Design reusable Remotion Elements for any Element library.
---
-# Element Guidelines
+# Creating Elements
-These guidelines cover how to design and build an Element that users can copy into their projects. They apply to the official gallery and to your own Element Library. To let users install Elements from your library's website, see [Integrating an Element Library with Studio](/docs/studio-protocol/component-library-integration).
+An Element is a reusable video building block written as a React component, such as an animated title, background, chart, or caption style. Browse the [Elements catalog](/elements) to see examples.
+
+When you [add an Element in Studio](/docs/studio/browse-elements), Studio copies its source code into your project and installs its dependencies. You can edit the copied code to change how it looks and behaves, or use its Inspector controls if it exposes them.
+
+This guide covers how to design and build Elements for the official catalog or your own Element Library. To let users install Elements from your library's website, see [Integrating an Element Library with Studio](/docs/studio-protocol/component-library-integration).
## Design
diff --git a/packages/docs/elements-sidebars.ts b/packages/docs/elements-sidebars.ts
index 19a3bf7df6..c8a138805e 100644
--- a/packages/docs/elements-sidebars.ts
+++ b/packages/docs/elements-sidebars.ts
@@ -3,21 +3,9 @@ import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
import {
elementCategories,
elementRegistry,
+ getElementCategoryHeadingId,
} from './src/components/Elements/element-registry';
-// Keep navigation alphabetical; the library uses the curated definitions array order.
-const compareStrings = (a: string, b: string) => {
- if (a < b) {
- return -1;
- }
-
- if (a > b) {
- return 1;
- }
-
- return 0;
-};
-
const sidebars: SidebarsConfig = {
elementsSidebar: [
{
@@ -27,35 +15,36 @@ const sidebars: SidebarsConfig = {
link: {type: 'doc', id: 'index'},
collapsible: false,
items: [
+ {
+ type: 'html',
+ value:
+ '<hr style="margin-top: 4px; margin-bottom: 4px; border-bottom: none"/>',
+ defaultStyle: true,
+ },
...elementCategories.map(({category, label}) => ({
type: 'category' as const,
label,
link: {type: 'doc' as const, id: `${category}/index`},
className: 'elements-sidebar-category',
+ customProps: {
+ catalogHref: `/elements/#${getElementCategoryHeadingId(category)}`,
+ },
collapsible: false,
// Keep membership for breadcrumbs, sidebar assignment, and active highlighting.
- // The category renderer displays only the link, not these children.
+ // The sidebar renderer displays only the category link.
items: Object.entries(elementRegistry)
.filter(([, metadata]) => metadata.category === category)
- .sort(([, a], [, b]) =>
- compareStrings(a.displayName, b.displayName),
- )
.map(([slug]) => `${slug}/index`),
})),
- {
- type: 'html',
- value:
- '<hr style="margin-top: 4px; margin-bottom: 4px; border-bottom: none"/>',
- defaultStyle: true,
- },
- {
- type: 'doc',
- id: 'guidelines',
- className: 'elements-sidebar-standalone-only',
- },
- 'libraries',
],
},
+ {
+ type: 'html',
+ value:
+ '<hr style="margin-top: 4px; margin-bottom: 4px; border-bottom: none"/>',
+ defaultStyle: true,
+ },
+ 'libraries',
],
};
diff --git a/packages/docs/elements/index.mdx b/packages/docs/elements/index.mdx
index 11453f73ae..9524f13b45 100644
--- a/packages/docs/elements/index.mdx
+++ b/packages/docs/elements/index.mdx
@@ -2,6 +2,8 @@
title: Remotion Elements
sidebar_label: Overview
hide_table_of_contents: true
+pagination_next: null
+pagination_prev: null
description: Drop-in, remixable video building blocks for Remotion.
---
diff --git a/packages/docs/elements/libraries.mdx b/packages/docs/elements/libraries.mdx
index bd64bfd63c..ac00bbdb59 100644
--- a/packages/docs/elements/libraries.mdx
+++ b/packages/docs/elements/libraries.mdx
@@ -1,6 +1,6 @@
---
title: Third-party Elements
-sidebar_label: Third-party Elements
+sidebar_label: More Elements
description: Third-party Element Libraries that integrate with Remotion Studio.
---
@@ -12,7 +12,7 @@ This is a list of third-party websites providing Remotion [Elements](/elements).
Click **Add to Studio** to register libraries in your project so you can quickly access them from Remotion Studio.
-Anybody can create Element Libraries. Follow the [Element guidelines](/elements/guidelines) when designing Elements, then read the [library integration guide](/docs/studio-protocol/component-library-integration) for instructions.
+Anybody can create Element Libraries. Follow the [Element guidelines](/docs/studio/creating-elements) when designing Elements, then read the [library integration guide](/docs/studio-protocol/component-library-integration) for instructions.
Contact [[email protected]](mailto:[email protected]) to propose inclusion of your Element Library on this page.
diff --git a/packages/docs/sidebars.ts b/packages/docs/sidebars.ts
index c9c8b7fc90..ea27fa44a5 100644
--- a/packages/docs/sidebars.ts
+++ b/packages/docs/sidebars.ts
@@ -1465,6 +1465,7 @@ const sidebars: SidebarsConfig = {
'studio/interactivity',
'studio/interactivity-best-practices',
'studio/make-component-interactive',
+ 'studio/creating-elements',
'studio/deploy-static',
'studio/deploy-server',
'studio/remotion-dev-new',
diff --git a/packages/docs/src/components/Elements/ElementLibrary.tsx b/packages/docs/src/components/Elements/ElementLibrary.tsx
index 194c560c11..a72732b88d 100644
--- a/packages/docs/src/components/Elements/ElementLibrary.tsx
+++ b/packages/docs/src/components/Elements/ElementLibrary.tsx
@@ -13,6 +13,7 @@ import {
setElementDragImage,
} from './element-drag-data';
import {
+ getElementCategoryHeadingId,
getElementDocumentationUrl,
getElementLibrarySections,
type ElementCategory,
@@ -401,7 +402,7 @@ export const ElementLibrary: React.FC<{
);
}
- const categoryHeadingId = `element-category-${section.category}`;
+ const categoryHeadingId = getElementCategoryHeadingId(section.category);
return (
<section
@@ -409,7 +410,10 @@ export const ElementLibrary: React.FC<{
aria-labelledby={categoryHeadingId}
className={styles.section}
>
- <h2 className={styles.categoryTitle} id={categoryHeadingId}>
+ <h2
+ className={`anchor ${styles.categoryTitle}`}
+ id={categoryHeadingId}
+ >
{section.label}
</h2>
<ElementGrid
diff --git a/packages/docs/src/components/Elements/ElementPage.module.css b/packages/docs/src/components/Elements/ElementPage.module.css
index e84e169d1c..0e0e1038bb 100644
--- a/packages/docs/src/components/Elements/ElementPage.module.css
+++ b/packages/docs/src/components/Elements/ElementPage.module.css
@@ -7,6 +7,11 @@
margin-bottom: 28px;
}
+.catalogLink {
+ flex-basis: 100%;
+ font-size: 0.875rem;
+}
+
.previewColumn {
flex: 3 1 700px;
min-width: 0;
diff --git a/packages/docs/src/components/Elements/ElementPage.tsx b/packages/docs/src/components/Elements/ElementPage.tsx
index dbdcee2944..5e44a035ff 100644
--- a/packages/docs/src/components/Elements/ElementPage.tsx
+++ b/packages/docs/src/components/Elements/ElementPage.tsx
@@ -1,4 +1,5 @@
import Head from '@docusaurus/Head';
+import Link from '@docusaurus/Link';
import {
isInsideStudio,
StudioProtocolInternals,
@@ -24,6 +25,7 @@ import {
createElementPayloadFromDefinition,
installElementInStudio,
} from './element-drag-data';
+import {getElementCategoryHeadingId} from './element-library-data';
import {getElementDimensionsLabel} from './element-utils';
import {ElementPreview} from './ElementPreview';
import {
@@ -169,6 +171,12 @@ export const ElementPage: React.FC<ElementPageProps> = ({
return (
<div className={styles.workbench}>
+ <Link
+ className={styles.catalogLink}
+ to={`/elements/#${getElementCategoryHeadingId(definition.category)}`}
+ >
+ ← All Elements
+ </Link>
<img
ref={posterRef}
alt=""
diff --git a/packages/docs/src/components/Elements/element-library-data.ts b/packages/docs/src/components/Elements/element-library-data.ts
index dc73e7991d..3edc100c83 100644
--- a/packages/docs/src/components/Elements/element-library-data.ts
+++ b/packages/docs/src/components/Elements/element-library-data.ts
@@ -2,6 +2,7 @@ import {
elementDefinitions,
type ElementDefinition,
} from './element-definitions';
+import {elementCategories as registeredCategories} from './element-registry';
type RegisteredElementDefinition = (typeof elementDefinitions)[number];
@@ -18,16 +19,14 @@ const elementCategories = Array.from(
);
export const getElementCategoryLabel = (category: ElementCategory) => {
- if (category === 'youtube') {
- return 'YouTube';
- }
-
- return category
- .split('-')
- .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
- .join(' ');
+ return (
+ registeredCategories.find((entry) => entry.category === category)?.label ??
+ category
+ );
};
+export {getElementCategoryHeadingId} from './element-registry';
+
export const isElementCategory = (
category: string,
): category is ElementCategory => {
diff --git a/packages/docs/src/components/Elements/element-registry.ts b/packages/docs/src/components/Elements/element-registry.ts
index 40ed152b02..ace2ba9523 100644
--- a/packages/docs/src/components/Elements/element-registry.ts
+++ b/packages/docs/src/components/Elements/element-registry.ts
@@ -14,6 +14,10 @@ export const elementCategories = [
export type ElementCategory = (typeof elementCategories)[number]['category'];
+export const getElementCategoryHeadingId = (category: ElementCategory) => {
+ return `element-category-${category}`;
+};
+
export const elementRegistry = {
'audio/oscilloscope': {
category: 'audio',
diff --git a/packages/docs/src/css/custom.css b/packages/docs/src/css/custom.css
index 3164cd0498..9d2a76e0ba 100644
--- a/packages/docs/src/css/custom.css
+++ b/packages/docs/src/css/custom.css
@@ -79,8 +79,7 @@ h6 {
/* The Elements library is also browsed inside Studio's iframe. */
.studio-elements-embed .theme-announcement-bar,
.studio-elements-embed .theme-doc-footer,
-.studio-elements-embed .pagination-nav,
-.studio-elements-embed .elements-sidebar-standalone-only {
+.studio-elements-embed .pagination-nav {
display: none;
}
@@ -137,7 +136,7 @@ html:has(.studio-caption-picker),
}
@media (max-width: 996px) {
- /* Keep the mobile sidebar toggle so categories remain navigable. */
+ /* Keep the mobile sidebar toggle for library navigation. */
.studio-elements-embed .navbar__items--right {
display: none;
}
@@ -153,6 +152,10 @@ html:has(.studio-caption-picker),
color: var(--ifm-menu-color);
}
+.theme-doc-sidebar-item-link > hr {
+ background-color: var(--border-color);
+}
+
:root {
--ifm-color-primary: #0b84f3;
--ifm-color-primary-dark: #0a77db;
diff --git a/packages/docs/src/data/articles.ts b/packages/docs/src/data/articles.ts
index 649639d3ea..973c254af3 100644
--- a/packages/docs/src/data/articles.ts
+++ b/packages/docs/src/data/articles.ts
@@ -8842,6 +8842,15 @@ export const articles = [
noAi: false,
slug: 'studio/browse-elements',
},
+ {
+ id: 'studio/creating-elements',
+ title: 'Creating Elements',
+ relativePath: 'docs/studio/creating-elements.mdx',
+ compId: 'articles-docs-studio-creating-elements',
+ crumb: null,
+ noAi: false,
+ slug: 'studio/creating-elements',
+ },
{
id: 'studio/delete-static-file',
title: 'deleteStaticFile()',
diff --git a/packages/docs/src/theme/DocSidebarItem/Category/index.tsx b/packages/docs/src/theme/DocSidebarItem/Category/index.tsx
index b2c6bf8477..67c0281ab3 100644
--- a/packages/docs/src/theme/DocSidebarItem/Category/index.tsx
+++ b/packages/docs/src/theme/DocSidebarItem/Category/index.tsx
@@ -4,23 +4,102 @@ import {isSamePath} from '@docusaurus/theme-common/internal';
import DocSidebarItemCategory from '@theme-original/DocSidebarItem/Category';
import type {Props} from '@theme/DocSidebarItem/Category';
import clsx from 'clsx';
-import React, {type ReactNode} from 'react';
+import React, {
+ createContext,
+ useContext,
+ useEffect,
+ useState,
+ type ReactNode,
+} from 'react';
+
+const ActiveElementCategoryContext = createContext<string | null>(null);
+
+const ElementsSidebarRoot: React.FC<Props> = (props) => {
+ const [activeHeadingId, setActiveHeadingId] = useState<string | null>(null);
+ const isCatalog = isSamePath(props.item.href, props.activePath);
+
+ useEffect(() => {
+ if (!isCatalog) {
+ return;
+ }
+
+ const headings = Array.from(
+ document.querySelectorAll<HTMLElement>('h2[id^="element-category-"]'),
+ );
+ let animationFrame: number | null = null;
+
+ const updateActiveCategory = () => {
+ animationFrame = null;
+ // Use the same offset as native anchor navigation, allowing subpixel rounding.
+ const scrollOffset =
+ Number.parseFloat(
+ getComputedStyle(document.documentElement).scrollPaddingTop,
+ ) || 0;
+ let activeId: string | null = null;
+ for (const heading of headings) {
+ if (heading.getBoundingClientRect().top <= scrollOffset + 1) {
+ activeId = heading.id;
+ }
+ }
+
+ setActiveHeadingId(activeId);
+ };
+
+ const scheduleUpdate = () => {
+ if (animationFrame === null) {
+ animationFrame = requestAnimationFrame(updateActiveCategory);
+ }
+ };
+
+ updateActiveCategory();
+ window.addEventListener('scroll', scheduleUpdate, {passive: true});
+ window.addEventListener('resize', scheduleUpdate);
+ return () => {
+ window.removeEventListener('scroll', scheduleUpdate);
+ window.removeEventListener('resize', scheduleUpdate);
+ if (animationFrame !== null) {
+ cancelAnimationFrame(animationFrame);
+ }
+ };
+ }, [isCatalog]);
+
+ return (
+ <ActiveElementCategoryContext.Provider value={activeHeadingId}>
+ <DocSidebarItemCategory {...props} />
+ </ActiveElementCategoryContext.Provider>
+ );
+};
export default function DocSidebarItemCategoryWrapper(props: Props): ReactNode {
const {item, activePath, onItemClick} = props;
+ const activeHeadingId = useContext(ActiveElementCategoryContext);
+ const catalogHref = item.customProps?.catalogHref;
- if (item.className !== 'elements-sidebar-category' || !item.href) {
+ if (item.className === 'elements-sidebar-root') {
+ return <ElementsSidebarRoot {...props} />;
+ }
+
+ if (
+ item.className !== 'elements-sidebar-category' ||
+ typeof catalogHref !== 'string'
+ ) {
return <DocSidebarItemCategory {...props} />;
}
+ const [catalogPath, headingId] = catalogHref.split('#');
+ const isCatalog = isSamePath(catalogPath, activePath);
+ const isActive = isCatalog
+ ? activeHeadingId === headingId
+ : isActiveSidebarItem(item, activePath);
+
return (
<li className={clsx('menu__list-item', item.className)}>
<Link
- to={item.href}
+ to={catalogHref}
className={clsx('menu__link', {
- 'menu__link--active': isActiveSidebarItem(item, activePath),
+ 'menu__link--active': isActive,
})}
- aria-current={isSamePath(item.href, activePath) ? 'page' : undefined}
+ aria-current={isCatalog && isActive ? 'location' : undefined}
tabIndex={props.tabIndex}
onClick={() => onItemClick?.(item)}
>
diff --git a/packages/docs/static/generated/articles-docs-studio-creating-elements.png b/packages/docs/static/generated/articles-docs-studio-creating-elements.png
new file mode 100644
index 0000000000..5d5bcdf8c9
Binary files /dev/null and b/packages/docs/static/generated/articles-docs-studio-creating-elements.png differ
diff --git a/packages/docs/vercel.ts b/packages/docs/vercel.ts
index 06dca2c23f..946db4ff39 100644
--- a/packages/docs/vercel.ts
+++ b/packages/docs/vercel.ts
@@ -90,6 +90,14 @@ export const config: VercelConfig = {
permanent: true,
}),
routes.redirect('/experimental_new', '/new', {permanent: true}),
+ routes.redirect('/elements/guidelines', '/docs/studio/creating-elements', {
+ permanent: true,
+ }),
+ routes.redirect(
+ '/elements/guidelines.md',
+ '/docs/studio/creating-elements.md',
+ {permanent: true},
+ ),
routes.redirect('/elements/contributing', '/docs/contributing/elements', {
permanent: true,
}),
diff --git a/packages/template-element-library/README.md b/packages/template-element-library/README.md
index 081440da00..b3101f02b6 100644
--- a/packages/template-element-library/README.md
+++ b/packages/template-element-library/README.md
@@ -35,7 +35,7 @@ Do these steps to add an Element:
The detail page, preview renderer, and Studio use the same source files. The gallery uses rendered previews. It does not use live Players.
-See the [Element guidelines](https://www.remotion.dev/elements/guidelines), [interactivity documentation](https://www.remotion.dev/docs/studio/interactivity), and [library integration guide](https://www.remotion.dev/docs/studio-protocol/component-library-integration) for layout, assets, dependencies, and installation requirements.
+See the [Element guidelines](https://www.remotion.dev/docs/studio/creating-elements), [interactivity documentation](https://www.remotion.dev/docs/studio/interactivity), and [library integration guide](https://www.remotion.dev/docs/studio-protocol/component-library-integration) for layout, assets, dependencies, and installation requirements.
## Render and upload previews