User Guide Cancel

Understanding the expression language

  1. After Effects User Guide
  2. Beta releases
    1. Beta Program Overview
    2. After Effects Beta Home
  3. Getting started
    1. Get started with After Effects
    2. What's new in After Effects 
    3. Release Notes | After Effects
    4. After Effects system requirements
    5. Keyboard shortcuts in After Effects
    6. Supported File formats | After Effects
    7. Hardware recommendations
    8. After Effects for Apple silicon
    9. Planning and setup
  4. Workspaces
    1. General user interface items
    2. Get to know After Effects interface
    3. Workflows
    4. Workspaces, panels, and viewers
  5. Projects and compositions
    1. Projects
    2. Composition basics
    3. Precomposing, nesting, and pre-rendering
    4. View detailed performance information with the Composition Profiler
    5. CINEMA 4D Composition Renderer
  6. Importing footage
    1. Preparing and importing still images
    2. Importing from After Effects and Adobe Premiere Pro
    3. Importing and interpreting video and audio
    4. Preparing and importing 3D image files
    5. Importing and interpreting footage items
    6. Working with footage items
    7. Detect edit points using Scene Edit Detection
    8. XMP metadata
  7. Text and Graphics
    1. Text
      1. Formatting characters and the Character panel
      2. Text effects
      3. Creating and editing text layers
      4. Formatting paragraphs and the Paragraph panel
      5. Extruding text and shape layers
      6. Animating text
      7. Examples and resources for text animation
      8. Live Text Templates
    2. Motion Graphics
      1. Work with Motion Graphics templates in After Effects
      2. Use expressions to create drop-down lists in Motion Graphics templates
      3. Work with Essential Properties to create Motion Graphics templates
      4. Replace images and videos in Motion Graphics templates and Essential Properties
      5. Animate faster and easier using the Properties panel
  8. Drawing, Painting, and Paths
    1. Overview of shape layers, paths, and vector graphics
    2. Paint tools: Brush, Clone Stamp, and Eraser
    3. Taper shape strokes
    4. Shape attributes, paint operations, and path operations for shape layers
    5. Use Offset Paths shape effect to alter shapes
    6. Creating shapes
    7. Create masks
    8. Remove objects from your videos with the Content-Aware Fill panel
    9. Roto Brush and Refine Matte
  9. Layers, Markers, and Camera
    1. Selecting and arranging layers
    2. Blending modes and layer styles
    3. 3D layers
    4. Layer properties
    5. Creating layers
    6. Managing layers
    7. Layer markers and composition markers
    8. Cameras, lights, and points of interest
  10. Animation, Keyframes, Motion Tracking, and Keying
    1. Animation
      1. Animation basics
      2. Animating with Puppet tools
      3. Managing and animating shape paths and masks
      4. Animating Sketch and Capture shapes using After Effects
      5. Assorted animation tools
      6. Work with Data-driven animation
    2. Keyframe
      1. Keyframe interpolation
      2. Setting, selecting, and deleting keyframes
      3. Editing, moving, and copying keyframes
    3. Motion tracking
      1. Tracking and stabilizing motion
      2. Face Tracking
      3. Mask Tracking
      4. Mask Reference
      5. Speed
      6. Time-stretching and time-remapping
      7. Timecode and time display units
    4. Keying
      1. Keying
      2. Keying effects
  11. Transparency and Compositing
    1. Compositing and transparency overview and resources
    2. Alpha channels and masks
    3. Track Mattes and Traveling Mattes
  12. Adjusting color
    1. Color basics
    2. Color management
    3. Color Correction effects
    4. OpenColorIO and ACES color management
  13. Effects and Animation Presets
    1. Effects and animation presets overview
    2. Effect list
    3. Effect Manager
    4. Simulation effects
    5. Stylize effects
    6. Audio effects
    7. Distort effects
    8. Perspective effects
    9. Channel effects
    10. Generate effects
    11. Time effects
    12. Transition effects
    13. The Rolling Shutter Repair effect
    14. Blur and Sharpen effects
    15. 3D Channel effects
    16. Utility effects
    17. Matte effects
    18. Noise and Grain effects
    19. Detail-preserving Upscale effect
    20. Obsolete effects
  14. Expressions and Automation
    1. Expressions
      1. Expression basics
      2. Understanding the expression language
      3. Using expression controls
      4. Syntax differences between the JavaScript and Legacy ExtendScript expression engines
      5. Editing expressions
      6. Expression errors
      7. Using the Expressions editor
      8. Use expressions to edit and access text properties
      9. Expression language reference
      10. Expression examples
    2. Automation
      1. Automation
      2. Scripts
  15. Immersive video, VR, and 3D
    1. Construct VR environments in After Effects
    2. Apply immersive video effects
    3. Compositing tools for VR/360 videos
    4. Advanced 3D Renderer
    5. Import and add 3D models to your composition
    6. Import 3D models from Creative Cloud Libraries
    7. Image-Based Lighting
    8. Extract and animate lights and cameras from 3D models
    9. Tracking 3D camera movement
    10. Cast and accept shadows
    11. Embedded 3D model animations
    12. Shadow Catcher
    13. 3D depth data extraction
    14. Modify materials properties of a 3D layer
    15. Work in 3D Design Space
    16. 3D Transform Gizmos
    17. Do more with 3D animation
    18. Preview changes to 3D designs real time with the Mercury 3D engine
    19. Add responsive design to your graphics 
  16. Views and Previews
    1. Previewing
    2. Video preview with Mercury Transmit
    3. Modifying and using views
  17. Rendering and Exporting
    1. Basics of rendering and exporting
    2. H.264 Encoding in After Effects
    3. Export an After Effects project as an Adobe Premiere Pro project
    4. Converting movies
    5. Multi-frame rendering
    6. Automated rendering and network rendering
    7. Rendering and exporting still images and still-image sequences
    8. Using the GoPro CineForm codec in After Effects
  18. Working with other applications
    1. Dynamic Link and After Effects
    2. Working with After Effects and other applications
      1. Export After Effects project as Premiere Pro project
    3. Sync Settings in After Effects
    4. Creative Cloud Libraries in After Effects
    5. Plug-ins
    6. Cinema 4D and Cineware
  19. Collaboration: Frame.io, and Team Projects
    1. Collaboration in Premiere Pro and After Effects
    2. Frame.io
      1. Install and activate Frame.io
      2. Use Frame.io with Premiere Pro and After Effects
      3. Frequently asked questions
    3. Team Projects
      1. Get Started with Team Projects
      2. Create a Team Project
      3. Collaborate with Team Projects
  20. Memory, storage, performance
    1. Memory and storage
    2. How After Effects handles low memory issues while previewing    
    3. Improve performance
    4. Preferences
    5. GPU and GPU driver requirements for After Effects
  21. Knowledge Base
    1. Known issues
    2. Fixed issues
    3. Frequently asked questions
    4. After Effects and macOS Ventura
    5. How After Effects handles low memory issues while previewing

Learn the expression language and use it to form different expressions in After Effects.

The After Effects expression language is based on JavaScript, with an extended set of built-in objects. After Effects uses the core standard JavaScript language, not the web browser–specific extensions, and contains its own set of extension objects, such as Layer, Comp, Footage, and Camera.

Though the expression language is based on a scripting language, a subtle but essential difference exists between a script and an expression. While a script tells an application to do something, an expression tells a property to do something.

When creating expressions, keep in mind the following:

  • The value of an expression is the value of the last statement evaluated. This is usually the last line of the expression. In its simplest form, the value of an expression is produced by the last variable or function called in the expression based on evaluation order. However, it can also be any value you explicitly reference as the return value. This can include values used much earlier in the expression for debugging purposes or values outside explicitly declared functions and variables that are not processed in the order they were written.
  • JavaScript is a case-sensitive language.
  • Functions should not be declared at the bottom of an expression.

Language basics

In JavaScript, a value stored in an object is called a property. However, After Effects uses the term property to refer to layer components as defined in the Timeline panel. For this reason, After Effects refers to JavaScript properties as either methods or attributes. In general practice, the difference between a method and an attribute is that a method usually does something to create its output (return) value, whereas an attribute simply refers to an existing value to determine its output (return) value. You can tell a method from an attribute most easily by looking for the parentheses following the method name, which surrounds any input arguments to the method.

An object is an item that can contain other objects, attributes, and methods. Compositions, layers, and footage items are examples of objects. Specifically, compositions, layers, and footage items are global objects, which means that they can be referred to in any context without reference to some higher-level object.

Accessing attributes and methods

You use the expression language to access attributes and methods of layer properties. To access a value, use a chain of object references separated by the period (.) operator. To chain object references past the layer level (for example, to refer to Effect properties, masks, or text animators), you can also use parentheses. For example, to link the Opacity property in Layer A to the Blurriness property of the Gaussian Blur effect in Layer B, enter the following expression in the expression field for the Opacity property for Layer A:

thisComp.layer("Layer B").effect("Gaussian Blur")("Blurriness")

Reading this expression from left to right, you progress from the higher-level, containing object down to the specific property:

  • The global object used refers to the current composition: thisComp.

  • A specific layer object within that composition is referred to by its name: layer("Layer B").

  • A specific effect object within that layer is referred to by its name: effect("Gaussian Blur").

  • A specific effect property within that effect is referred to by its name: ("Blurriness").

For the nth component of a multidimensional property, like the y component of an effect control point, append [n] at the end, like this:

thisComp.layer("Layer B").effect("Advanced Lightning")("Origin")[1]

The default object for an expression is the property on which the expression is written, followed by the layer containing the expression; therefore, you do not need to specify the property. For example, a wiggle expression written on the Position property of a layer can be either of the following:

wiggle(5, 10)  
position.wiggle(5, 10) 
thisProperty.wiggle(5, 10)

Include the layer and property when retrieving them from outside the layer and the property on which the expression is written. For example, an expression written on the Opacity property of Layer B, linking it to the Rotation property of Layer A would look like this expression:

thisComp.layer("Layer A").rotation
Note:

To see more examples of how expressions work, use the pick whip to link one layer property to another and look at the expressions it creates.

Arrays and multidimensional properties

An Array is a type of object that stores an ordered set of numbers. An Array is represented as a list of numbers separated by commas and surrounded by brackets, as in this example:

  [10, 23]

You can assign an Array object to a variable, making it easy to refer to array values in other areas of the expression. For example:

  myArray = [10, 23]

The dimension of an Array object is the number of elements in the array. The dimension of myArray is 2. Different properties in After Effects have different dimensions depending on the number of value arguments they have. In the expression language, the values of properties are either single values (Number objects) or arrays (Array objects).

The following table provides examples of some properties and their dimensions:

Dimension

Property

1

Rotation °

Opacity %

2

Scale [x=width, y=height]

Position [x, y]

Anchor Point [x, y]

Audio Levels [left, right]

3

Scale [width, height, depth]

3D Position [x, y, z]

3D Anchor Point [x, y, z]

Orientation [x, y, z]

4

Color [red, green, blue, alpha]

You can access the individual elements of an Array object by using brackets and an index number to indicate which element you want. The elements in an Array object are indexed starting from 0. Using the previous example, myArray[0] is 10 and myArray[1] is 23.

The following two expressions are equivalent:

  [myArray[0], 5] 
  [10, 5]

Position property arrays

The Position property arrays are indexed as follows:

  • position[0] is the x coordinate of position.

  • position[1] is the y coordinate of position.

  • position[2] is the z coordinate of position.

Representation of colors in Arrays

Colors are represented as 4D arrays:

  • Red
  • Green
  • Blue
  • Alpha

In projects with a color depth of 8 bpc or 16 bpc, each value in a color array ranges from 0 (black) to 1 (white). For example, red can range from 0 (no color) to 1 (red). So, [0,0,0,0] is black and transparent, and [1,1,1,1] is white and opaque. In projects with a color depth of 32 bpc, values under 0 and over 1 are allowed.

If you use an index that is greater than the index of the highest-dimension component in an Array object, After Effects returns an error. For example, myArray[2] causes an error, but position[2] returns the z coordinate of Position.

Many of the properties and methods in the After Effects expression language take Array objects as arguments or return them as values. For example, thisLayer.position is an Array object that is either two-dimensional or three-dimensional depending on whether the layer is 2D or 3D.

Examples

If you want to write an expression that keeps the y value of an animation of Position but fixes the x value at 9, you would use the following:

  y = position[1]; 
  [9,y]

The following is even more succinct:

  [9, position[1]]

This is an important point, so let’s look at one more example. If you want to combine the x position value from Layer A with the y position value from Layer B, you would use the following:

  x = thisComp.layer("Layer A").position[0];  
  y = thisComp.layer("Layer B").position[1];  
  [x,y]

You can create an expression that refers to just one value within the array of a 2D or 3D property. By default, the first value is used, unless you specify otherwise. For example, if you drag the pick whip from the Rotation property of Layer A to the Scale property of Layer B, the following expression appears:

  thisComp.layer("Layer B").scale[0]

By default, this expression uses the first value of the Scale property, which is width. If you prefer to use the height value instead, drag the pick whip directly to the second value instead of the property name, or change the expression as follows:

  thisComp.layer("Layer B").scale[1]

Conversely, if you drag the pick whip from the Scale property of Layer B to the Rotation property of Layer A, After Effects automatically creates a variable, assigns the one-dimensional Rotation property value to it, and then uses that variable for both dimensions of the Scale property:

  temp = thisComp.layer(1).transform.rotation; 
  [temp, temp]

Vectors

In After Effects, many properties and methods take or return vectors. After Effects refers to an array as a vector if it represents either a point or direction in space. For example, After Effects describes position as returning a vector.

However, though a function like audioLevels does return a two-dimensional value (the left and right channel levels), it is not called a vector because it does not represent a point or direction. Some functions in After Effects accept vector arguments, but they are generally only useful when the values passed represent a direction. For example, cross(vec1, vec2) computes a third vector that is at right angles to the input vectors. The cross product is useful when vec1 and vec2 are two vectors representing directions in space, but not if they just represent two arbitrary collections of numbers.

Indices and labels

Indexing for Layer, Effect, and Mask elements in After Effects starts from 1. For example, the first layer in the Timeline panel is layer(1).

Generally, it's best to use the name of a layer, effect, or mask instead of a number to avoid confusion and errors if the layer, effect, or mask is moved or if the arguments are changed during product updates and upgrades. When you use a name, always enclose it in straight quotes. For example, the first of these expressions are easier to understand than the second expression, and the first expression continues to work even if you change the order of effects:

  effect("Colorama").param("Get Phase From")  
  effect(1).param(2)

Expression time

Time within an expression is always in composition time (not layer time) and is measured in seconds - (This is not the case with the sourceRectAtTime() expression). The default time for any expression is the current composition time at which the expression is being evaluated. The following expressions both use the default composition time and return the same values:

thisComp.layer(1).position  
thisComp.layer(1).position.valueAtTime(time)

To use a relative time, add an incremental time value to the time argument. For example, to get the Position value 5 seconds before the current time, use the following expression:

thisComp.layer(1).position.valueAtTime(time-5)

Default time references to properties in nested compositions use the original default composition time, not remapped time. However, if you use the source function to retrieve a property, the remapped time is used.

For example, if the source of a layer in the containing composition is a nested composition, and in the containing composition, you have remapped time when you get the position values of a layer in the nested composition with the following expression, the position values use the default time of the composition:

comp("nested composition").layer(1).position

However, if you access layer 1 using the source function, the position values use the remapped time:

thisComp.layer("nested composition").source.layer(1).position
Note:

If you use a specific time in an expression, After Effects ignores the remapped time.

Because expressions operate on time in units of seconds (not frames), you sometimes need to use time conversion methods to convert time values to perform operations on frames.

Example: Use the expression language reference to write an expression

Follow along with this example to learn how to use the After Effects expression language reference to write expressions. The expression created in this example links the Position property of Solid 2 to the Position property of Solid 1, with the movement of Solid 2 offset by 2 seconds from the movement of Solid 1.

  1. Create two solid layers– Solid 1 and Solid 2.

  2. Animate the Position property values for Solid 1 using keyframes. (See About animation, keyframes, and expressions.)

  3. Select the Position property for Solid 2 and choose Animation > Add Expression or Alt-click (Windows) or Option-click the stopwatch   button for the property. The following expression appears by default:

      transform.position
  4. Type the following directly over transform.position:

      thisComp
  5. The element thisComp is a global attribute whose value is a Comp object representing the current composition. To determine what can follow thisComp in your expression, look up the return value for thisComp under Global objects, attributes, and methods.

    Note that thisComp returns a Comp object. Next, look at Comp attributes and methods to see which attributes and methods you can use with a Comp object. One option is layer(index). The index, or number, inside the parentheses, specify the layer that you want to use. For this example, let's assume that Solid 1 is the first layer in your composition. To retrieve values from the first layer in the active composition, type .layer(1) at the end of the expression to get the following:

      thisComp.layer(1)
  6. Again, look at the expression elements reference to see that layer(index) returns a Layer object. Look at Layer General attributes and methods, and find the element you want to use. For example, if you want to get the values of the Position property for the layer, type .position at the end of the expression to get the following:

      thisComp.layer(1).position
  7. From Layer General attributes and methods, you can see that the position attribute returns a property. Look up Property attributes and methods and notice that you can add a time factor to the expression. To add a specific time, such as current time plus 2 seconds, type .valueAtTime(time+2) at the end of the expression to get the following:

      thisComp.layer(1).position.valueAtTime(time+2)
  8. From Property attributes and methods, notice that the valueAtTime method returns a Number or Array. When an expression returns a Number, Array, or Boolean (true or false), you cannot add further attributes or methods to the expression (if you want, however, you can add arithmetic operators, such as +, -, *, and /).

More Expression resources

Now that you have understood some of the concepts behind expressions, come to the community for some real-life examples, and to share your work.

The AE Enhancers forum also provides many examples and much information about expressions, as well as scripts and animation presets.

Get help faster and easier

New user?