Skip to content

πŸŽ₯ Make videos programmatically with React

`@remotion/studio`: Document inferred prop controls

JonnyBurgerde9b8bdfa935
diff --git a/packages/docs/docs/composition.mdx b/packages/docs/docs/composition.mdx
index 9819ac1227..dcddd1864c 100644
--- a/packages/docs/docs/composition.mdx
+++ b/packages/docs/docs/composition.mdx
@@ -63,6 +63,8 @@ If you use `lazyComponent`, Remotion will use React Suspense to load the compone
Give your component default props. Default props can be overriden using the [Props editor](/docs/visual-editing) and with [Input Props](/docs/props-resolution).
+Since <AvailableFrom v="4.0.516" inline />, the Studio infers basic Props editor controls from the values in `defaultProps`. A [`schema`](#schema) is not required.
+
Props must be an object that contains only pure JSON-serializable values.
Functions, classes, and other non-serializable values will be lost while rendering.
(This restriction does not apply to the [`<Player>`](/docs/player/player), where you are allowed to pass functions as props.)
@@ -85,9 +87,11 @@ Use a `type`, not an `interface` to type your `defaultProps`. [Learn why](/docs/
See: [`calculateMetadata()`](/docs/calculate-metadata)
-### `schema`
+### `schema?`
+
+Pass a top-level [`z.object()`](https://zod.dev/?id=objects) schema which your default props must satisfy. The schema validates the props and customizes their [visual editing controls](/docs/visual-editing).
-Pass a Zod schema which your default props must satisfy. By doing so, you enable [visual editing](/docs/visual-editing). See: [Define a schema](/docs/schemas)
+If omitted, the Studio infers basic controls from `defaultProps`. An explicit schema takes precedence over the inferred controls. See: [Define a schema](/docs/schemas).
## Example using `component`
diff --git a/packages/docs/docs/parameterized-rendering.mdx b/packages/docs/docs/parameterized-rendering.mdx
index b5d1004839..cf0311203b 100644
--- a/packages/docs/docs/parameterized-rendering.mdx
+++ b/packages/docs/docs/parameterized-rendering.mdx
@@ -32,10 +32,10 @@ To determine the data which gets passed to the video, the following steps are ta
The default props define the shape of the data.
</li>
<li>
-A schema can be defined and validated.
+A schema may optionally be defined to validate the data and customize the visual controls.
</li>
<li>
-In absence of data, default props can be edited in the Remotion Studio.
+In absence of data, default props can be edited in the Remotion Studio. Basic controls are inferred from their values.
</li>
</ul>
<Step>2</Step> <strong>Input props</strong> may be specified when rendering a video to override the default props.<br/>
diff --git a/packages/docs/docs/passing-props.mdx b/packages/docs/docs/passing-props.mdx
index 8a152595f7..746db3ecc4 100644
--- a/packages/docs/docs/passing-props.mdx
+++ b/packages/docs/docs/passing-props.mdx
@@ -73,9 +73,11 @@ export const Root: React.FC = () => {
Default props are useful so you don't preview your video with no data. [Default props will be overriden by input props](/docs/props-resolution).
-## Define a schema<AvailableFrom v="4.0.0"/>
+Since <AvailableFrom v="4.0.516" inline />, Remotion also infers basic [visual editing controls](/docs/visual-editing) from the values in `defaultProps`.
-You can use [Zod](https://github.com/colinhacks/zod) to [define a typesafe schema for your composition](/docs/schemas).
+## Optional: Define a schema<AvailableFrom v="4.0.0"/>
+
+You can use [Zod](https://github.com/colinhacks/zod) to [define a typesafe schema for your composition](/docs/schemas). A schema is not required for visual editing. Add one when you need validation, constraints, choices or specialized controls.
## Input props
diff --git a/packages/docs/docs/schemas.mdx b/packages/docs/docs/schemas.mdx
index a74853b908..0fd35ec141 100644
--- a/packages/docs/docs/schemas.mdx
+++ b/packages/docs/docs/schemas.mdx
@@ -6,7 +6,9 @@ sidebar_label: Defining a schema
crumb: 'How To'
---
-As an alternative to [using TypeScript types](/docs/parameterized-rendering) to define the shape of the props your component accepts, you may use [Zod](https://zod.dev/) to define a schema for your props. You may do so if you want to edit the props visually in the Remotion Studio.
+Use [Zod](https://zod.dev/) to validate the props your component accepts and to customize their controls in the Remotion Studio.
+
+You do not need to define a schema to [edit props visually](/docs/visual-editing). Since <AvailableFrom v="4.0.516" inline />, Remotion infers basic controls from [`defaultProps`](/docs/composition#defaultprops). Define a schema when you need validation, constraints, choices or specialized controls.
## AI agent prompt
@@ -16,23 +18,25 @@ Use this prompt to make an existing composition parameterizable:
Make this Remotion composition parameterizable in Remotion Studio.
Find the component that is passed to <Composition> and the file where the composition is registered.
-Define a z.object() schema that describes the props the component accepts.
-Use z.infer<typeof schema> as the React component prop type.
-Attach the schema to the <Composition> using the schema prop.
-Add defaultProps to the <Composition> that match the schema and preserve the current rendered output.
+Define a TypeScript type that describes the props the component accepts.
+Add defaultProps to the <Composition> that match the type and preserve the current rendered output.
+Keep defaultProps as an inline object literal so Remotion can infer visual controls and save changes back to the file.
-If zod or @remotion/zod-types are missing, install them with npx remotion add @remotion/zod-types zod.
+If zod is missing, install it with npx remotion add zod.
+Only add a Zod schema when the props need validation, constraints, choices, descriptions or specialized controls.
Keep the existing composition behavior unchanged except for making the props editable in Remotion Studio.
```
## Prerequisites
-If you want to use this feature, install `zod` and [`@remotion/zod-types`](/docs/zod-types) for Remotion-specific types:
+To define a schema, install `zod`:
```bash
-npx remotion add @remotion/zod-types zod
+npx remotion add zod
```
+Install [`@remotion/zod-types`](/docs/zod-types) as well if you want to use Remotion-specific types such as [`zColor()`](/docs/zod-types/z-color), [`zTextarea()`](/docs/zod-types/z-textarea) or [`zMatrix()`](/docs/zod-types/z-matrix).
+
## Defining a schema
To define a schema for your props, use [`z.object()`](https://zod.dev/?id=objects):
@@ -116,7 +120,7 @@ export const RemotionRoot: React.FC = () => {
## Editing props visually
-When you have defined a schema for your props, you can [edit them visually in the Remotion Studio](/docs/visual-editing). This is useful if you want to quickly try out different values for your props.
+The schema determines which controls appear when you [edit props visually in the Remotion Studio](/docs/visual-editing). It overrides the controls that Remotion would otherwise infer from `defaultProps`.
## Supported types
diff --git a/packages/docs/docs/studio/interactivity-best-practices.mdx b/packages/docs/docs/studio/interactivity-best-practices.mdx
index cae3bbc4d1..f366f9fc49 100644
--- a/packages/docs/docs/studio/interactivity-best-practices.mdx
+++ b/packages/docs/docs/studio/interactivity-best-practices.mdx
@@ -144,6 +144,7 @@ Make this interactive in the Remotion Studio: https://www.remotion.dev/docs/stud
When scaffolding a composition, keep `width`, `height`, `fps`, `durationInFrames` and [`defaultProps`](/docs/composition#defaultprops) inline and make no type assertions.
The Props editor can save visual edits back to your code when `defaultProps` is an inline object literal on `<Composition>` or [`<Still>`](/docs/still).
+Since <AvailableFrom v="4.0.516" inline />, it also infers basic controls from these values, so a Zod schema is not required.
```tsx
// πŸ‘ Static values are in <Composition>, dynamic values are in calculateMetadata()
diff --git a/packages/docs/docs/visual-editing.mdx b/packages/docs/docs/visual-editing.mdx
index 85eb5af7e3..62f97f7210 100644
--- a/packages/docs/docs/visual-editing.mdx
+++ b/packages/docs/docs/visual-editing.mdx
@@ -8,7 +8,9 @@ crumb: 'How To'
<YouTube minutes={6} href="https://www.youtube.com/watch?v=NX9YTOsLGpQ" thumb="https://i.ytimg.com/vi/NX9YTOsLGpQ/hq720.jpg" title="Visual editing" />
-You can edit the default props of a component visually, first register a [`schema`](/docs/composition#schema) with your [`<Composition>`](/docs/composition).
+You can edit the [`defaultProps`](/docs/composition#defaultprops) of a [`<Composition>`](/docs/composition) visually in the Remotion Studio.
+
+Basic controls are inferred from the values in `defaultProps`. You do not need to define a [`schema`](/docs/composition#schema).
## Opening the default props editor
@@ -23,6 +25,33 @@ When editing a `<Sequence>` visually in the timeline, the visual style controls
## Supported controls
+### Inferred from `defaultProps`<AvailableFrom v="4.0.516" />
+
+If no `schema` is specified, Remotion infers controls for:
+
+- Strings
+- Numbers
+- Booleans
+- Dates
+- Nested objects
+- Colors, if [`@remotion/zod-types`](/docs/zod-types) is installed
+- [`staticFile()`](/docs/staticfile) assets
+- Non-empty arrays whose items have the same inferred type
+
+Fields named `type` are treated as literals and cannot be edited. This prevents changing a discriminator without defining the other possible object shapes.
+
+`null`, `undefined`, empty arrays, arrays with mixed item types and values whose type cannot be inferred do not get a visual control. Define an explicit schema if these values should be editable.
+
+`zod` must be installed for Remotion to infer controls:
+
+```bash title="Install Zod"
+npx remotion add zod
+```
+
+### Defined by a schema
+
+Define a [Zod schema](/docs/schemas) when you need validation, constraints or specialized controls. An explicit schema takes precedence over the controls inferred from `defaultProps`.
+
Controls are implemented for:
- `z.object()`
@@ -45,7 +74,7 @@ Controls are implemented for:
## Editing JSON
-Alternatively, you can edit the JSON schema directly by pressing `JSON` in the props editor. Changes will not apply if the schema is invalid.
+Alternatively, you can edit the props as JSON by pressing `JSON` in the props editor. Changes will not apply if the props are invalid.
## Saving default props to your code
@@ -54,14 +83,13 @@ Remotion can statically analyze your root file and allow you to save props back
```tsx twoslash title="Inlined defaultProps" {15-18}
// @filename: MyComponent.tsx
import React from 'react';
-import {z} from 'zod';
-export const myCompSchema = z.object({
- propOne: z.string(),
- propTwo: z.string(),
-});
+type Props = {
+ propOne: string;
+ propTwo: string;
+};
-export const MyComponent: React.FC<z.infer<typeof myCompSchema>> = ({propOne, propTwo}) => {
+export const MyComponent: React.FC<Props> = ({propOne, propTwo}) => {
return (
<div>
<h1>{propOne}</h1>
@@ -75,7 +103,7 @@ export const MyComponent: React.FC<z.infer<typeof myCompSchema>> = ({propOne, pr
// ---cut---
import React from 'react';
import {Composition} from 'remotion';
-import {MyComponent, myCompSchema} from './MyComponent';
+import {MyComponent} from './MyComponent';
export const RemotionRoot: React.FC = () => {
return (
@@ -86,7 +114,6 @@ export const RemotionRoot: React.FC = () => {
fps={30}
width={1920}
height={1080}
- schema={myCompSchema}
defaultProps={{
propOne: 'Hello World',
propTwo: 'Welcome to Remotion',