InteractivitySchema<AvailableFrom v="4.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

import {Interactive, type InteractivitySchema} from 'remotion';

export const titleCardSchema = {
  ...Interactive.baseSchema,
  ...Interactive.transformSchema,
  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, freeze, hidden, name and showInTimeline.

Interactive.captionsSchema<AvailableFrom v="4.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.cropSchema<AvailableFrom v="4.0.500" />

Crop props inherited from an absolute-fill <Sequence>: cropLeft, cropRight, cropTop and cropBottom.

Use this fragment to opt a custom component into crop controls. The component must apply the crop props to its rendered element or forward them to an absolute-fill <Sequence>.

Interactive.textSchema<AvailableFrom v="4.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 <AvailableFrom v="4.0.486" inline />.

Interactive.backgroundSchema<AvailableFrom v="4.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.borderSchema<AvailableFrom v="4.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.borderRadiusSchema<AvailableFrom v="4.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.

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.

font-family<AvailableFrom v="4.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.

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-captions<AvailableFrom v="4.0.500" />

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

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.

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 and color fields.

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

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

defaultKeyframeOutput?<AvailableFrom v="4.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.

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.

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.

See also

• Interactive.withSchema()
• Interactive
• createEffect()
• Defining a schema for your props
• Source code for these types