Skip to main content

InteractivitySchemav4.0.479

An InteractivitySchema describes controls that Remotion Studio can show in the timeline.

It is used by Interactive.withSchema() for component props and by createEffect() for effect parameters.

This schema is not a Zod schema. Use Zod schemas for <Composition> props.

Example​

schema.ts
import type {InteractivitySchema} from 'remotion';

export const titleCardSchema = {
  tint: {
    type: 'color',
    default: '#ffffff',
    description: 'Tint',
  },
} as const satisfies InteractivitySchema;

Keys may use dot notation. For example, a key named style.opacity reads from and writes to props.style.opacity.

Reusable component schemas​

Interactive exposes schema fragments for custom components:

Interactive.baseSchema​

Timeline props inherited from <Sequence>: durationInFrames, from, trimBefore, playbackRate, freeze, hidden, name and showInTimeline.

Interactive.withSchema() includes this fragment and uses it for its <Sequence>.

Interactive.captionsSchemav4.0.500​

A captions field for components that accept Caption[] data. It enables the captions inspector and is not keyframable.

This schema fragment is headless: it does not render an element or add layout, transform, or text-style controls. Add other Interactive schema fragments only when the component renders and supports those props.

Interactive.transformSchema​

Transform-related style props: style.transformOrigin, style.translate, style.scale, style.rotate and style.opacity.

Interactive.withSchema() includes this fragment.

Interactive.cropSchemav4.0.500​

Controls for cropping a component from each edge: cropLeft, cropRight, cropTop and cropBottom.

Interactive.withSchema() includes this fragment and applies the crop through the component's style prop.

Interactive.textSchemav4.0.481​

Text-related style props: style.color, style.fontFamily, style.fontSize, style.lineHeight, style.fontWeight, style.fontStyle, style.textAlign and style.letterSpacing.

style.fontFamily is available from v4.0.486.

Interactive.backgroundSchemav4.0.497​

A color control for style.backgroundColor.

The backgroundColor longhand is used rather than the background shorthand so complex backgrounds such as gradients and images can remain untouched.

Interactive.borderSchemav4.0.497​

Border-related style props: style.borderWidth, style.borderStyle and style.borderColor.

The longhand properties are used rather than the border shorthand, because React does not expand shorthands. This lets each control read its own value, and allows style.borderWidth and style.borderColor to be animated.

Interactive.borderRadiusSchemav4.0.501​

Corner radius style props: style.borderRadius, style.borderTopLeftRadius, style.borderTopRightRadius, style.borderBottomRightRadius and style.borderBottomLeftRadius.

The Studio shows either the shorthand or the four longhands. Mixing style.borderRadius with a corner longhand is treated as computed and cannot be edited visually.

When style.borderRadius is a number or contains one to four pixel values, the Studio expands it into the four longhand properties when you edit a corner. Complex values such as percentages and elliptical radii are not editable.

Interactive.premountSchema​

Mounting props: premountFor and postmountFor.

Interactive.withSchema() includes this fragment and uses the props for its <Sequence>.

These schemas are for component props. Effects created with createEffect() should define only their own effect parameters.

Field Types​

number​

Shows a numeric control.

boolean​

Shows an on/off control.

color​

Shows a color control. The value is a CSS color string.

text-content​

Shows a text control for a string prop, such as a title.

Remotion Studio can edit a string literal, such as title="Hello". Other expressions are shown as read-only.

Text content fields are not keyframable.

schema.ts
import type {InteractivitySchema} from 'remotion';

export const schema = {
  title: {
    type: 'text-content',
    default: '',
    description: 'Title',
  },
} as const satisfies InteractivitySchema;

asset​

Shows a control for selecting an asset source.

assetType?v4.0.521​

Set to 'audio', 'video' or 'image' to only show matching files when replacing this field's asset in Remotion Studio.

assetType describes the intended content. It does not inspect or validate the current value or remote URLs.

schema.ts
import type {InteractivitySchema} from 'remotion';

export const schema = {
  audioSrc: {
    type: 'asset',
    assetType: 'audio',
    default: 'https://example.com/audio.mp3',
    description: 'Audio source',
  },
} as const satisfies InteractivitySchema;

font-familyv4.0.485​

Shows a font family control. The value is a CSS font family string.

When choosing a Google Font in Studio, Remotion adds the matching loadFont() call from @remotion/google-fonts to the composition file.

font-weight​

Shows a font weight control. The value is a number such as 700 or a CSS font weight string such as "bold".

Keyframes are written as interpolate() calls with outputType: 'font-weight'.

enum​

Shows a select control. Each variant can define its own nested InteractivitySchema.

array​

Shows a list of values. Array fields are not keyframable.

remotion-captionsv4.0.500​

Marks a prop containing Caption[] data for the captions inspector. Caption fields are not keyframable.

The inspector can edit caption text and toggle pageBreakAfter for each caption.

rotation-css​

Shows a rotation control backed by a CSS rotation string such as "15deg".

rotation-degrees​

Shows a rotation control backed by a number in degrees.

translate​

Shows a two-axis CSS translate control such as "10px 20px".

transform-origin​

Shows a transform origin control such as "50% 50%".

scale​

Shows a scale control. The value may be a number or a CSS scale string.

uv-coordinate​

Shows a normalized two-dimensional coordinate as [x, y].

[0, 0] is the top-left corner and [1, 1] is the bottom-right corner.

visual?​

Optional metadata for drawing related Visual Mode controls in the preview.

This metadata does not change the stored value. It only tells Remotion Studio how a uv-coordinate relates to other schema fields.

Line​

Draws a line from this coordinate to another uv-coordinate field in the same schema.

start: {
  type: 'uv-coordinate',
  default: [0, 0],
  visual: {
    type: 'line',
    to: 'end',
  },
},
end: {
  type: 'uv-coordinate',
  default: [1, 1],
},
Ellipse​

Draws an ellipse centered on this coordinate. The width, height, rotation and innerScale properties point to numeric fields in the same schema.

center: {
  type: 'uv-coordinate',
  default: [0.5, 0.5],
  visual: {
    type: 'ellipse',
    width: 'width',
    height: 'height',
    rotation: 'rotation',
    innerScale: 'start',
  },
},
width: {
  type: 'number',
  default: 1,
  hiddenFromList: false,
},
height: {
  type: 'number',
  default: 1,
  hiddenFromList: false,
},
rotation: {
  type: 'rotation-degrees',
  default: 0,
},
start: {
  type: 'number',
  min: 0,
  max: 1,
  default: 0,
  hiddenFromList: false,
},

innerScale is optional. When present, Remotion Studio draws a second ellipse using the same center, width, height and rotation multiplied by that numeric field.

svg-path​

Shows an SVG path control. The value is an SVG path string, as used by the d attribute.

Keyframes are written as interpolatePaths() calls from @remotion/paths.

hidden​

Keeps a field in the schema without rendering a visible control.

Common Properties​

type​

The control type. Must be one of the field types listed above.

default​

The value used when no prop value is present.

For required effect parameters, use default: undefined.

description?​

The label shown in Remotion Studio.

keyframable?​

Controls whether the field can be animated with keyframes.

Default: true for number, boolean, rotation-css, rotation-degrees, translate, transform-origin, scale, uv-coordinate, color, font-weight and svg-path fields.

Boolean fields use hold keyframes: their value changes at the next keyframe without blending. Boolean keyframes are available from v4.0.530.

array, asset, font-family, text-content and remotion-captions fields are not keyframable. Fields inside an enum variant schema can still be keyframed according to their own keyframable setting.

enum fields are not keyframable by default. From v4.0.509, set keyframable: true to enable hold keyframes. Remotion Studio generates Easing.step1 segments because enum values cannot be blended.

Set keyframable: false on a keyframable field to show a static control.

defaultKeyframeOutput?v4.0.490​

Applies to number and scale fields.

Controls the output option used when Remotion Studio turns a static value into an interpolate() call. Default: 'linear'.

Set it to 'perceptual-scale' for values representing scale. Existing interpolations keep their current output setting.

min?​

The minimum value for numeric controls.

max?​

The maximum value for numeric controls.

step?​

The increment used by numeric and spatial controls when dragging or using arrow keys. It does not restrict values typed into the Inspector.

integer?v4.0.528​

Set to true if the prop is a number and requires a whole number. Remotion Studio will reject non-integer values. Default: false.

hiddenFromList​

Applies to number fields.

When true, the field is not listed by default in the timeline controls list. Default: false.

Enum Fields​

variants​

Maps each selectable value to a nested InteractivitySchema.

Only the active variant's nested fields are applied to props.

enum-schema.ts
import type {InteractivitySchema} from 'remotion';

export const boxSchema = {
  layout: {
    type: 'enum',
    default: 'absolute-fill',
    description: 'Layout',
    variants: {
      'absolute-fill': {
        'style.opacity': {
          type: 'number',
          min: 0,
          max: 1,
          step: 0.01,
          default: 1,
          description: 'Opacity',
          hiddenFromList: false,
        },
      },
      none: {},
    },
  },
} as const satisfies InteractivitySchema;

Array Fields​

item​

Defines the field type for every item in the array.

newItemDefault​

The value inserted when the user adds an item.

minLength?​

The minimum number of items.

maxLength?​

The maximum number of items.

Compatibility​

BrowsersServersEnvironments
Chrome
Firefox
Safari
Node.js
Bun
Serverless Functions

The schema describes plain data. Editing its controls requires Remotion Studio.

See also​