Skip to content

πŸŽ₯ Make videos programmatically with React

`@remotion/studio`: Add default prop inference guide

JonnyBurgera77b19fd96de
diff --git a/packages/docs/docs/composition.mdx b/packages/docs/docs/composition.mdx
index dcddd1864c..f16dc968fe 100644
--- a/packages/docs/docs/composition.mdx
+++ b/packages/docs/docs/composition.mdx
@@ -63,7 +63,7 @@ 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.
+Since <AvailableFrom v="4.0.516" inline />, the Studio [infers basic Props editor controls from the values in `defaultProps`](/docs/default-props-inference). 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.
@@ -91,7 +91,7 @@ See: [`calculateMetadata()`](/docs/calculate-metadata)
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).
-If omitted, the Studio infers basic controls from `defaultProps`. An explicit schema takes precedence over the inferred controls. See: [Define a schema](/docs/schemas).
+If omitted, the Studio [infers basic controls from `defaultProps`](/docs/default-props-inference). An explicit schema takes precedence over the inferred controls. See: [Define a schema](/docs/schemas).
## Example using `component`
diff --git a/packages/docs/docs/default-props-inference.mdx b/packages/docs/docs/default-props-inference.mdx
new file mode 100644
index 0000000000..851d65e222
--- /dev/null
+++ b/packages/docs/docs/default-props-inference.mdx
@@ -0,0 +1,111 @@
+---
+image: /generated/articles-docs-default-props-inference.png
+id: default-props-inference
+title: Inferring controls from default props
+sidebar_label: Inferring controls
+crumb: 'How To'
+---
+
+# Inferring controls from default props<AvailableFrom v="4.0.516" />
+
+If a [`<Composition>`](/docs/composition) has [`defaultProps`](/docs/composition#defaultprops) but no [`schema`](/docs/composition#schema), the Remotion Studio infers controls from the values in `defaultProps`.
+
+```tsx twoslash title="src/Root.tsx"
+import {Composition} from 'remotion';
+
+type Props = {
+ title: string;
+ color: string;
+ showLogo: boolean;
+};
+
+const MyComponent: React.FC<Props> = () => null;
+
+export const RemotionRoot: React.FC = () => {
+ return (
+ <Composition
+ id="my-video"
+ component={MyComponent}
+ durationInFrames={150}
+ fps={30}
+ width={1920}
+ height={1080}
+ defaultProps={{
+ title: 'Hello',
+ color: '#0b84ff',
+ showLogo: true,
+ }}
+ />
+ );
+};
+```
+
+This creates a text control for `title`, a color control for `color` and a checkbox for `showLogo`. The `schema` prop is not required.
+
+## Inference rules
+
+| Value in `defaultProps` | Inferred control |
+| ---------------------------------------------------- | ------------------------------------------------------------------------- |
+| String | Text input |
+| CSS color | Color picker |
+| Value returned by [`staticFile()`](/docs/staticfile) | Asset picker |
+| Number | Number input |
+| Boolean | Checkbox |
+| `Date` | Date and time input |
+| Plain object | Nested controls |
+| Non-empty array | Array editor, if every item matches the type inferred from the first item |
+
+Color inference requires [`@remotion/zod-types`](/docs/zod-types). A string is treated as a color if its property name contains `color` and its value is a valid CSS color, or if it uses unambiguous CSS color syntax such as `#`, `rgb()`, `hsl()` or `oklch()`.
+
+Nested values are inferred recursively.
+
+## Values without an editable control
+
+The Studio does not infer an editable control for:
+
+- `null`
+- `undefined`
+- Empty arrays
+- Arrays whose items do not match the inferred type
+- Class instances and other values whose type is not recognized
+
+A property named `type` is inferred as a literal and is not editable. This prevents changing a discriminator without defining the object shapes for its other possible values.
+
+Use an explicit [Zod schema](/docs/schemas) if one of these values should be editable.
+
+## Explicit schemas take precedence
+
+If you pass a `schema` to [`<Composition>`](/docs/composition), Remotion uses it instead of inferring controls from `defaultProps`.
+
+Define a schema when you need:
+
+- Runtime validation
+- Enums, unions, optional values or nullable values
+- Number constraints such as `.min()`, `.max()` and `.step()`
+- Descriptions
+- Specialized controls such as [`zTextarea()`](/docs/zod-types/z-textarea) and [`zMatrix()`](/docs/zod-types/z-matrix)
+
+Inference configures the Studio controls. It does not add runtime validation to renders outside the Studio.
+
+## Requirements
+
+Install `zod` so the Studio can infer controls:
+
+```bash title="Install Zod"
+npx remotion add zod
+```
+
+Install [`@remotion/zod-types`](/docs/zod-types) to additionally infer color controls:
+
+```bash title="Install Remotion Zod types"
+npx remotion add @remotion/zod-types
+```
+
+The `defaultProps` object does not need to be inline for inference. Keep it inline if you want the Studio to [save edited values back to your source code](/docs/visual-editing#saving-default-props-to-your-code).
+
+## See also
+
+- [Visual editing](/docs/visual-editing)
+- [Defining a schema](/docs/schemas)
+- [Passing props](/docs/passing-props)
+- [`<Composition>`](/docs/composition)
diff --git a/packages/docs/docs/parameterized-rendering.mdx b/packages/docs/docs/parameterized-rendering.mdx
index cf0311203b..a2ffb3e41b 100644
--- a/packages/docs/docs/parameterized-rendering.mdx
+++ b/packages/docs/docs/parameterized-rendering.mdx
@@ -35,7 +35,7 @@ The default props define the shape of the data.
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. Basic controls are inferred from their values.
+In absence of data, default props can be edited in the Remotion Studio. [Basic controls are inferred from their values](/docs/default-props-inference).
</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 746db3ecc4..37b08840c5 100644
--- a/packages/docs/docs/passing-props.mdx
+++ b/packages/docs/docs/passing-props.mdx
@@ -73,7 +73,7 @@ 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).
-Since <AvailableFrom v="4.0.516" inline />, Remotion also infers basic [visual editing controls](/docs/visual-editing) from the values in `defaultProps`.
+Since <AvailableFrom v="4.0.516" inline />, Remotion also [infers basic visual editing controls](/docs/default-props-inference) from the values in `defaultProps`.
## Optional: Define a schema<AvailableFrom v="4.0.0"/>
diff --git a/packages/docs/docs/schemas.mdx b/packages/docs/docs/schemas.mdx
index 0fd35ec141..a9ba445b94 100644
--- a/packages/docs/docs/schemas.mdx
+++ b/packages/docs/docs/schemas.mdx
@@ -8,7 +8,7 @@ crumb: 'How To'
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.
+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/default-props-inference). Define a schema when you need validation, constraints, choices or specialized controls.
## AI agent prompt
@@ -120,7 +120,7 @@ export const RemotionRoot: React.FC = () => {
## Editing props visually
-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`.
+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`](/docs/default-props-inference).
## Supported types
diff --git a/packages/docs/docs/studio/interactivity-best-practices.mdx b/packages/docs/docs/studio/interactivity-best-practices.mdx
index f366f9fc49..a9c758a8be 100644
--- a/packages/docs/docs/studio/interactivity-best-practices.mdx
+++ b/packages/docs/docs/studio/interactivity-best-practices.mdx
@@ -144,7 +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.
+Since <AvailableFrom v="4.0.516" inline />, it also [infers basic controls from these values](/docs/default-props-inference), 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 62f97f7210..8e69b3314e 100644
--- a/packages/docs/docs/visual-editing.mdx
+++ b/packages/docs/docs/visual-editing.mdx
@@ -10,7 +10,7 @@ crumb: 'How To'
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).
+Basic controls are [inferred from the values in `defaultProps`](/docs/default-props-inference). You do not need to define a [`schema`](/docs/composition#schema).
## Opening the default props editor
@@ -27,26 +27,7 @@ When editing a `<Sequence>` visually in the timeline, the visual style 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
-```
+If no `schema` is specified, Remotion infers controls from `defaultProps`. See [Inferring controls from default props](/docs/default-props-inference) for the supported values, edge cases and installation requirements.
### Defined by a schema
diff --git a/packages/docs/sidebars.ts b/packages/docs/sidebars.ts
index 8f0aa55c91..8c542321a0 100644
--- a/packages/docs/sidebars.ts
+++ b/packages/docs/sidebars.ts
@@ -1163,6 +1163,7 @@ const sidebars: SidebarsConfig = {
},
items: [
'passing-props',
+ 'default-props-inference',
'schemas',
'visual-editing',
'data-fetching',
diff --git a/packages/docs/src/data/articles.ts b/packages/docs/src/data/articles.ts
index c0ce3e96ca..cf8be751e9 100644
--- a/packages/docs/src/data/articles.ts
+++ b/packages/docs/src/data/articles.ts
@@ -1475,6 +1475,15 @@ export const articles = [
noAi: false,
slug: 'dataset-render',
},
+ {
+ id: 'default-props-inference',
+ title: 'Inferring controls from default props',
+ relativePath: 'docs/default-props-inference.mdx',
+ compId: 'articles-docs-default-props-inference',
+ crumb: 'How To',
+ noAi: false,
+ slug: 'default-props-inference',
+ },
{
id: 'delay-render',
title: 'delayRender() and continueRender()',
diff --git a/packages/docs/static/generated/articles-docs-default-props-inference.png b/packages/docs/static/generated/articles-docs-default-props-inference.png
new file mode 100644
index 0000000000..5e02b56351
Binary files /dev/null and b/packages/docs/static/generated/articles-docs-default-props-inference.png differ