Skip to content

🎥 Make videos programmatically with React

Elements: Add fallback guidance for failed library installs

Igor Samokhovetsd3e2a885753f
diff --git a/packages/docs/src/components/Elements/ElementInstallFallbackModal.tsx b/packages/docs/src/components/Elements/ElementInstallFallbackModal.tsx
index 3d5043a55b..70421d37e2 100644
--- a/packages/docs/src/components/Elements/ElementInstallFallbackModal.tsx
+++ b/packages/docs/src/components/Elements/ElementInstallFallbackModal.tsx
@@ -5,6 +5,7 @@ import {ElementStudioAction} from './ElementStudioAction';
import styles from './ElementInstallFallbackModal.module.css';
export const ElementInstallFallbackModal: React.FC<{
+ readonly buttonLabel: string;
readonly definition: ElementDefinition;
readonly installFailureCount: number;
readonly isInstalling: boolean;
@@ -14,6 +15,7 @@ export const ElementInstallFallbackModal: React.FC<{
readonly posterRef: RefObject<HTMLImageElement | null>;
readonly sourceCode: string;
}> = ({
+ buttonLabel,
definition,
installFailureCount,
isInstalling,
@@ -97,11 +99,14 @@ export const ElementInstallFallbackModal: React.FC<{
Use this element
</h3>
<p className={styles.description}>
- Open a Remotion Studio, then click below.
+ <a href="/docs/studio" target="_blank" rel="noreferrer">
+ Open a Remotion Studio
+ </a>
+ , then click below.
</p>
<div className={styles.installAction}>
<ElementStudioAction
- buttonLabel={installFailureCount > 1 ? 'Oops!' : 'Install'}
+ buttonLabel={buttonLabel}
definition={definition}
loading={isInstalling}
onClick={onInstall}
diff --git a/packages/docs/src/components/Elements/ElementLibrary.tsx b/packages/docs/src/components/Elements/ElementLibrary.tsx
index 9947546cb1..bbc23894c9 100644
--- a/packages/docs/src/components/Elements/ElementLibrary.tsx
+++ b/packages/docs/src/components/Elements/ElementLibrary.tsx
@@ -15,6 +15,7 @@ import {
} from './element-library-data';
import {ElementInstallFallbackModal} from './ElementInstallFallbackModal';
import {ELEMENT_PREVIEW_BACKGROUND} from './ElementPreviewComposition';
+import {useStudioInstallFallback} from './use-studio-install-fallback';
import styles from './ElementLibrary.module.css';
const reducedMotionQuery = '(prefers-reduced-motion: reduce)';
@@ -49,8 +50,13 @@ const ElementCard: React.FC<{
const [isPointerOver, setIsPointerOver] = useState(false);
const [playbackFailed, setPlaybackFailed] = useState(false);
const [isInstalling, setIsInstalling] = useState(false);
- const [isInstallFallbackOpen, setIsInstallFallbackOpen] = useState(false);
- const [installFailureCount, setInstallFailureCount] = useState(0);
+ const {
+ buttonLabel,
+ closeFallback,
+ failureCount,
+ isFallbackOpen,
+ showFallback,
+ } = useStudioInstallFallback('Install');
const posterRef = useRef<HTMLImageElement>(null);
const videoRef = useRef<HTMLVideoElement>(null);
const shouldPlay =
@@ -91,21 +97,18 @@ const ElementCard: React.FC<{
try {
const result = await installElementInStudio({definition, sourceCode});
if (!result.success) {
- setInstallFailureCount((count) => count + 1);
- setIsInstallFallbackOpen(true);
+ showFallback();
return;
}
- setIsInstallFallbackOpen(false);
- setInstallFailureCount(0);
+ closeFallback();
if (window.location.origin === 'https://www.remotion.dev') {
navigator.sendBeacon(
`https://www.remotion.pro/api/track/element-install-request?slug=${encodeURIComponent(definition.slug)}`,
);
}
} catch {
- setInstallFailureCount((count) => count + 1);
- setIsInstallFallbackOpen(true);
+ showFallback();
} finally {
setIsInstalling(false);
}
@@ -193,14 +196,12 @@ const ElementCard: React.FC<{
</BlueButton>
</div>
<ElementInstallFallbackModal
+ buttonLabel={buttonLabel}
definition={definition}
- installFailureCount={installFailureCount}
+ installFailureCount={failureCount}
isInstalling={isInstalling}
- isOpen={isInstallFallbackOpen}
- onClose={() => {
- setIsInstallFallbackOpen(false);
- setInstallFailureCount(0);
- }}
+ isOpen={isFallbackOpen}
+ onClose={closeFallback}
onInstall={installElement}
posterRef={posterRef}
sourceCode={sourceCode}
diff --git a/packages/docs/src/components/Elements/ElementLibraryInstallFallbackModal.module.css b/packages/docs/src/components/Elements/ElementLibraryInstallFallbackModal.module.css
new file mode 100644
index 0000000000..9a4c9f9aa0
--- /dev/null
+++ b/packages/docs/src/components/Elements/ElementLibraryInstallFallbackModal.module.css
@@ -0,0 +1,126 @@
+.dialog {
+ width: min(440px, calc(100vw - 32px));
+ max-width: none;
+ margin: auto;
+ padding: 0;
+ border: 0;
+ border-radius: 8px;
+ background: var(--ifm-background-surface-color);
+ box-shadow: 0 24px 70px rgb(0 0 0 / 35%);
+ color: var(--ifm-font-color-base);
+}
+
+.dialog::backdrop {
+ background: rgb(0 0 0 / 45%);
+ backdrop-filter: blur(2px);
+}
+
+.content {
+ position: relative;
+ padding: 20px;
+ font-size: 0.875rem;
+ line-height: 1.5;
+}
+
+.closeButton {
+ position: absolute;
+ top: 12px;
+ right: 12px;
+ display: flex;
+ width: 32px;
+ height: 32px;
+ align-items: center;
+ justify-content: center;
+ padding: 0;
+ border: 0;
+ border-radius: 8px;
+ background: transparent;
+ color: var(--ifm-color-emphasis-700);
+ cursor: pointer;
+ font: inherit;
+ font-size: 1.5rem;
+ line-height: 1;
+}
+
+.closeButton:hover {
+ background: var(--ifm-color-emphasis-100);
+}
+
+.closeButton:focus-visible,
+.copyButton:focus-visible,
+.url:focus-visible {
+ outline: 2px solid var(--ifm-color-primary);
+ outline-offset: 2px;
+}
+
+.title {
+ margin: 0;
+ padding-right: 32px;
+ font-size: 1rem;
+ line-height: 1.5;
+}
+
+.description p {
+ margin: 12px 0;
+}
+
+.manualTitle {
+ margin: 20px 0 8px;
+ font-size: inherit;
+}
+
+.instructions {
+ margin: 0 0 12px;
+}
+
+.urlField {
+ position: relative;
+}
+
+.url {
+ display: block;
+ width: 100%;
+ min-width: 0;
+ box-sizing: border-box;
+ padding: 8px 44px 8px 10px;
+ border: 1px solid var(--ifm-color-emphasis-300);
+ border-radius: 4px;
+ background: var(--ifm-color-emphasis-100);
+ color: inherit;
+ font: inherit;
+}
+
+.copyButton {
+ position: absolute;
+ top: 50%;
+ right: 4px;
+ display: flex;
+ width: 32px;
+ height: 32px;
+ align-items: center;
+ justify-content: center;
+ padding: 0;
+ transform: translateY(-50%);
+ border: 0;
+ border-radius: 4px;
+ background: transparent;
+ color: var(--ifm-color-emphasis-700);
+ cursor: pointer;
+}
+
+.copyButton:hover {
+ background: var(--ifm-color-emphasis-200);
+ color: var(--ifm-font-color-base);
+}
+
+.copyStatus {
+ margin: 8px 0 0;
+}
+
+.copyStatus:empty {
+ display: none;
+}
+
+.configHint {
+ margin: 16px 0 0;
+}
diff --git a/packages/docs/src/components/Elements/ElementLibraryInstallFallbackModal.tsx b/packages/docs/src/components/Elements/ElementLibraryInstallFallbackModal.tsx
new file mode 100644
index 0000000000..d8a24fed1b
--- /dev/null
+++ b/packages/docs/src/components/Elements/ElementLibraryInstallFallbackModal.tsx
@@ -0,0 +1,210 @@
+import type {AddElementLibraryToStudioErrorCode} from '@remotion/studio-protocol';
+import React, {
+ useEffect,
+ useId,
+ useLayoutEffect,
+ useRef,
+ useState,
+ type RefObject,
+} from 'react';
+import {createPortal} from 'react-dom';
+import {BlueButton} from '../../../components/layout/Button';
+import type {ThirdPartyElementLibrary} from './third-party-element-library-data';
+import styles from './ElementLibraryInstallFallbackModal.module.css';
+
+export const ElementLibraryInstallFallbackModal: React.FC<{
+ readonly buttonLabel: string;
+ readonly library: ThirdPartyElementLibrary;
+ readonly failure: {
+ readonly code: AddElementLibraryToStudioErrorCode | null;
+ readonly message: string;
+ } | null;
+ readonly isAdding: boolean;
+ readonly onClose: () => void;
+ readonly onAdd: () => void;
+ readonly triggerRef: RefObject<HTMLButtonElement | null>;
+}> = ({
+ buttonLabel,
+ library,
+ failure,
+ isAdding,
+ onClose,
+ onAdd,
+ triggerRef,
+}) => {
+ const dialogRef = useRef<HTMLDialogElement>(null);
+ const titleId = useId();
+ const [copyState, setCopyState] = useState<'idle' | 'copied' | 'error'>(
+ 'idle',
+ );
+
+ useLayoutEffect(() => {
+ const dialog = dialogRef.current;
+ const trigger = triggerRef.current;
+ if (!dialog) {
+ return;
+ }
+
+ dialog.showModal();
+ return () => {
+ if (dialog.open) {
+ dialog.close();
+ }
+
+ // A successful retry re-enables the trigger in the same commit.
+ window.requestAnimationFrame(() => {
+ if (trigger?.isConnected) {
+ trigger.focus();
+ }
+ });
+ };
+ }, [triggerRef]);
+
+ useEffect(() => {
+ if (copyState !== 'copied') {
+ return;
+ }
+
+ const timeout = window.setTimeout(() => setCopyState('idle'), 2000);
+ return () => window.clearTimeout(timeout);
+ }, [copyState]);
+
+ return createPortal(
+ <dialog
+ ref={dialogRef}
+ aria-labelledby={titleId}
+ className={styles.dialog}
+ onCancel={(event) => {
+ event.preventDefault();
+ onClose();
+ }}
+ onClick={(event) => {
+ if (event.target !== event.currentTarget) {
+ return;
+ }
+
+ const bounds = event.currentTarget.getBoundingClientRect();
+ if (
+ event.clientX < bounds.left ||
+ event.clientX > bounds.right ||
+ event.clientY < bounds.top ||
+ event.clientY > bounds.bottom
+ ) {
+ onClose();
+ }
+ }}
+ >
+ <div className={styles.content}>
+ <button
+ aria-label="Close"
+ className={styles.closeButton}
+ onClick={onClose}
+ type="button"
+ >
+ ×
+ </button>
+ <h3 className={styles.title} id={titleId}>
+ Add {library.displayName} to Studio
+ </h3>
+ <div aria-live="polite" className={styles.description}>
+ {isAdding ? (
+ <p>Finding a compatible Remotion Studio…</p>
+ ) : failure?.code === 'no-compatible-studio' ? (
+ <p>
+ <a href="/docs/studio" target="_blank" rel="noreferrer">
+ Open a Remotion Studio
+ </a>
+ , then try again.
+ </p>
+ ) : failure?.code === 'no-configurable-target' ? (
+ <p>Focus your Remotion Studio tab, then try again.</p>
+ ) : failure?.code === 'studio-upgrade-required' ? (
+ <p>
+ {failure.message}{' '}
+ <a href="/docs/upgrading" target="_blank" rel="noreferrer">
+ How to upgrade Remotion.
+ </a>
+ </p>
+ ) : (
+ <p>{failure?.message}</p>
+ )}
+ </div>
+ <BlueButton fullWidth loading={isAdding} onClick={onAdd} size="sm">
+ {buttonLabel}
+ </BlueButton>
+ <h4 className={styles.manualTitle}>Add manually</h4>
+ <p className={styles.instructions}>
+ In your local Studio, open <strong>Settings</strong>, select{' '}
+ <strong>Elements</strong>, then choose <strong>Add by URL</strong> and
+ paste this URL:
+ </p>
+ <div className={styles.urlField}>
+ <input
+ aria-label={`${library.displayName} library URL`}
+ className={styles.url}
+ onFocus={(event) => event.currentTarget.select()}
+ readOnly
+ value={library.libraryUrl}
+ />
+ <button
+ aria-label="Copy URL"
+ className={styles.copyButton}
+ onClick={async () => {
+ try {
+ await navigator.clipboard.writeText(library.libraryUrl);
+ setCopyState('copied');
+ } catch {
+ setCopyState('error');
+ }
+ }}
+ title="Copy URL"
+ type="button"
+ >
+ <svg
+ aria-hidden="true"
+ width="16"
+ height="16"
+ viewBox="0 0 24 24"
+ fill="none"
+ stroke="currentColor"
+ strokeWidth="2"
+ strokeLinecap="round"
+ strokeLinejoin="round"
+ >
+ {copyState === 'copied' ? (
+ <path d="m5 12 4 4L19 6" />
+ ) : (
+ <>
+ <rect x="9" y="9" width="13" height="13" rx="2" />
+ <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />
+ </>
+ )}
+ </svg>
+ </button>
+ </div>
+ <p aria-live="polite" className={styles.copyStatus}>
+ {copyState === 'copied'
+ ? 'Copied.'
+ : copyState === 'error'
+ ? 'Could not copy. Select the URL above and copy it manually.'
+ : null}
+ </p>
+ <p className={styles.configHint}>
+ Then click <strong>+ Add Element Library</strong> in Studio.
+ </p>
+ <p className={styles.configHint}>
+ You can also add this URL to <code>remotion.config.ts</code> using{' '}
+ <a
+ href="/docs/config#addelementlibrary"
+ target="_blank"
+ rel="noreferrer"
+ >
+ <code>Config.addElementLibrary()</code>
+ </a>
+ .
+ </p>
+ </div>
+ </dialog>,
+ document.body,
+ );
+};
diff --git a/packages/docs/src/components/Elements/ThirdPartyElementLibraries.module.css b/packages/docs/src/components/Elements/ThirdPartyElementLibraries.module.css
index 93e5de78d4..d2b87344d3 100644
--- a/packages/docs/src/components/Elements/ThirdPartyElementLibraries.module.css
+++ b/packages/docs/src/components/Elements/ThirdPartyElementLibraries.module.css
@@ -96,28 +96,6 @@
z-index: 1;
}
-.loadingStatus,
-.successStatus,
-.errorStatus {
- position: relative;
- z-index: 1;
- margin: 10px 0 0;
- font-size: 0.875rem;
- line-height: 1.45;
-}
-
-.loadingStatus {
- color: var(--ifm-color-emphasis-700);
-}
-
-.successStatus {
- color: var(--ifm-color-success-dark);
-}
-
-.errorStatus {
- color: var(--ifm-color-danger-dark);
-}
-
@container third-party-libraries (min-width: 640px) {
.list {
grid-template-columns: repeat(2, minmax(0, 1fr));
diff --git a/packages/docs/src/components/Elements/ThirdPartyElementLibraries.tsx b/packages/docs/src/components/Elements/ThirdPartyElementLibraries.tsx
index 919f986d35..acc5b3df53 100644
--- a/packages/docs/src/components/Elements/ThirdPartyElementLibraries.tsx
+++ b/packages/docs/src/components/Elements/ThirdPartyElementLibraries.tsx
@@ -3,18 +3,20 @@ import {
isInsideStudio,
type AddElementLibraryToStudioErrorCode,
} from '@remotion/studio-protocol';
-import React, {useCallback, useId, useLayoutEffect, useState} from 'react';
+import React, {useCallback, useLayoutEffect, useRef, useState} from 'react';
import {BlueButton} from '../../../components/layout/Button';
+import {ElementLibraryInstallFallbackModal} from './ElementLibraryInstallFallbackModal';
import {
thirdPartyElementLibraries,
type ThirdPartyElementLibrary,
} from './third-party-element-library-data';
+import {useStudioInstallFallback} from './use-studio-install-fallback';
import styles from './ThirdPartyElementLibraries.module.css';
type AddState =
| {readonly type: 'idle'}
| {readonly type: 'loading'}
- | {readonly message: string; readonly type: 'awaiting-confirmation'}
+ | {readonly type: 'awaiting-confirmation'}
| {
readonly code: AddElementLibraryToStudioErrorCode | null;
readonly message: string;
@@ -27,8 +29,11 @@ const ThirdPartyElementLibraryItem: React.FC<{
readonly requestLibraryAddition: typeof addElementLibraryToStudio;
}> = ({isEmbeddedInStudio, library, requestLibraryAddition}) => {
const [addState, setAddState] = useState<AddState>({type: 'idle'});
- const statusId = useId();
+ const {buttonLabel, closeFallback, isFallbackOpen, showFallback} =
+ useStudioInstallFallback('Add to Studio');
+ const addButtonRef = useRef<HTMLButtonElement>(null);
const isLoading = addState.type === 'loading';
+ const isSent = addState.type === 'awaiting-confirmation';
const addToStudio = useCallback(async () => {
setAddState({type: 'loading'});
@@ -44,13 +49,12 @@ const ThirdPartyElementLibraryItem: React.FC<{
message: result.message,
type: 'error',
});
+ showFallback();
return;
}
- setAddState({
- message: `Request sent to ${result.target.projectName ?? 'Remotion Studio'}. Confirm adding ${library.displayName} inside Studio.`,
- type: 'awaiting-confirmation',
- });
+ closeFallback();
+ setAddState({type: 'awaiting-confirmation'});
} catch {
setAddState({
code: null,
@@ -58,39 +62,15 @@ const ThirdPartyElementLibraryItem: React.FC<{
'Could not send the request to Remotion Studio. Check that Studio is running, then try again.',
type: 'error',
});
+ showFallback();
}
- }, [library.libraryUrl, library.displayName, requestLibraryAddition]);
-
- let status: React.ReactNode = null;
- if (addState.type === 'awaiting-confirmation') {
- status = (
- <p
- aria-live="polite"
- className={styles.successStatus}
- id={statusId}
- role="status"
- >
- {addState.message}
- </p>
- );
- } else if (addState.type === 'error') {
- status = (
- <p className={styles.errorStatus} id={statusId} role="alert">
- {addState.message}{' '}
- {addState.code === 'no-compatible-studio' ? (
- <a href="/docs/studio">How to start Studio.</a>
- ) : addState.code === 'studio-upgrade-required' ? (
- <a href="/docs/upgrading">How to upgrade Remotion.</a>
- ) : null}
- </p>
- );
- } else if (isLoading) {
- status = (
- <p aria-live="polite" className={styles.loadingStatus} id={statusId}>
- Finding a compatible Remotion Studio…
- </p>
- );
- }
+ }, [
+ closeFallback,
+ library.libraryUrl,
+ library.displayName,
+ requestLibraryAddition,
+ showFallback,
+ ]);
return (
<li className={styles.card}>
@@ -112,12 +92,15 @@ const ThirdPartyElementLibraryItem: React.FC<{
</a>
</h3>
<BlueButton
+ ref={addButtonRef}
aria-busy={isLoading}
- aria-describedby={addState.type === 'idle' ? undefined : statusId}
+ aria-live="polite"
aria-label={
isLoading
? `Adding ${library.displayName} to Studio`
- : `Add ${library.displayName} to Studio`
+ : isSent
+ ? `Sent ${library.displayName} to Studio`
+ : `Add ${library.displayName} to Studio`
}
className={styles.addAction}
fullWidth={false}
@@ -128,14 +111,26 @@ const ThirdPartyElementLibraryItem: React.FC<{
title={
isLoading
? `Adding ${library.displayName} to Studio`
- : `Add ${library.displayName} to Studio`
+ : isSent
+ ? `Sent ${library.displayName} to Studio`
+ : `Add ${library.displayName} to Studio`
}
>
- Add to Studio
+ {isSent ? 'Sent to Studio' : 'Add to Studio'}
</BlueButton>
</div>
- {status}
</div>
+ {isFallbackOpen ? (
+ <ElementLibraryInstallFallbackModal
+ buttonLabel={buttonLabel}
+ failure={addState.type === 'error' ? addState : null}
+ isAdding={isLoading}
+ library={library}
+ onAdd={addToStudio}
+ onClose={closeFallback}
+ triggerRef={addButtonRef}
+ />
+ ) : null}
</li>
);
};
diff --git a/packages/docs/src/components/Elements/use-studio-install-fallback.ts b/packages/docs/src/components/Elements/use-studio-install-fallback.ts
new file mode 100644
index 0000000000..2258454510
--- /dev/null
+++ b/packages/docs/src/components/Elements/use-studio-install-fallback.ts
@@ -0,0 +1,27 @@
+import {useCallback, useState} from 'react';
+
+export const useStudioInstallFallback = (actionLabel: string) => {
+ const [fallbackState, setFallbackState] = useState({
+ failureCount: 0,
+ isOpen: false,
+ });
+
+ const showFallback = useCallback(() => {
+ setFallbackState((state) => ({
+ failureCount: state.failureCount + 1,
+ isOpen: true,
+ }));
+ }, []);
+
+ const closeFallback = useCallback(() => {
+ setFallbackState({failureCount: 0, isOpen: false});
+ }, []);
+
+ return {
+ buttonLabel: fallbackState.failureCount > 1 ? 'Oops!' : actionLabel,
+ closeFallback,
+ failureCount: fallbackState.failureCount,
+ isFallbackOpen: fallbackState.isOpen,
+ showFallback,
+ };
+};