π₯ 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.mdxindex 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 componeGive 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.mdxnew file mode 100644index 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.mdxindex 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.mdxindex 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.mdxindex 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 typesdiff --git a/packages/docs/docs/studio/interactivity-best-practices.mdx b/packages/docs/docs/studio/interactivity-best-practices.mdxindex 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/studWhen 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.mdxindex 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 schemadiff --git a/packages/docs/sidebars.ts b/packages/docs/sidebars.tsindex 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.tsindex 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.pngnew file mode 100644index 0000000000..5e02b56351Binary files /dev/null and b/packages/docs/static/generated/articles-docs-default-props-inference.png differ