π₯ 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.mdxindex 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 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.+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.mdxindex 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 taThe 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.mdxindex 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 propsdiff --git a/packages/docs/docs/schemas.mdx b/packages/docs/docs/schemas.mdxindex a74853b908..0fd35ec141 100644--- a/packages/docs/docs/schemas.mdx+++ b/packages/docs/docs/schemas.mdx@@ -6,7 +6,9 @@ sidebar_label: Defining a schemacrumb: '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 schemaTo 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 typesdiff --git a/packages/docs/docs/studio/interactivity-best-practices.mdx b/packages/docs/docs/studio/interactivity-best-practices.mdxindex 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/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.```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 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.tsximport 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',