Dynamic Lower Thirds: Building Reusable Social Overlays with GroupLayer

If you have ever built an automated video pipeline—whether for a SaaS dashboard, a social media factory, or a personalized onboarding flow—you know that overlays are the most frequent point of failure. Aligning a name label over a background bar, synchronizing their entry animations, and ensuring they scale correctly across different resolutions usually involves a mess of frame math and fragile coordinate offsets.

In VideoFlow, we solve this with the GroupLayer. Instead of managing individual layers on a global timeline, you can group them into a single logical unit that shares a coordinate space, a lifecycle, and even cinematic transitions.

In this tutorial, we will build a professional, reusable "Lower Third" overlay using @videoflow/core that you can drop into any video project.

The Problem with Manual Overlays

Most video-as-code tools treat every layer as an independent entity. If you want a nameplate to slide in from the left, you have to animate the background rectangle and the text layer separately. If you decide to move the nameplate 50 pixels to the right, you have to update both layers. This "flat" approach doesn't scale for complex cinematic assets.

VideoFlow's GroupLayer changes the mental model. It allows you to treat a collection of layers as a single visual object. When you animate the group, everything inside it follows.

Step 1: Defining the Group

To build a lower third, we need a background shape and a text label. We wrap these inside a $.group call. This creates a private flow where timing is relative to the group's start.

import VideoFlow from '@videoflow/core';

const $ = new VideoFlow({ width: 1920, height: 1080 });

// Create a reusable lower third group
$.group(
  { position: [0.1, 0.85] }, // Position the entire group in the bottom-left
  { transitionIn: { transition: 'slideRight', duration: '600ms' } },
  (g) => {
    // 1. Add the background bar
    g.addShape({
      width: 40, 
      height: 8, 
      fill: '#FF5A1F', // VideoFlow Orange
      cornerRadius: '0.5em',
      opacity: 0.9,
      position: [0, 0], // Relative to group center
    });

    // 2. Add the name text
    g.addText({
      text: 'ALEX RENDER',
      fontSize: 4,
      color: '#ffffff',
      fontWeight: 700,
      position: [0, 0],
    });
  }
);

$.wait('5s');

Step 2: Synchronizing Animations

One of the most powerful features of the VideoFlow builder API is that groups inherit the standard animation methods. Because the group is a single layer, you can apply a transitionIn to the whole assembly. In the example above, the slideRight preset will move both the background and the text as a single unit.

If you want to get more advanced, you can stack GLSL effects on the group. Adding a glow or a vignette to the group will apply the effect to the composited result of its children, which is much more performant than applying it to each child individually.

Step 3: Making it Dynamic

Since VideoFlow is just TypeScript, we can easily turn this into a function. This is the foundation of a "video template" system. You can store these configurations in a database as JSON and render them on demand.

function addLowerThird($, name, title) {
  return $.group({ position: [0.1, 0.8] }, {}, (g) => {
    g.addShape({ width: 50, height: 10, fill: '#111', opacity: 0.8 });
    
    g.parallel((p) => {
       p.addText({ text: name, fontSize: 4, position: [0, -0.1] });
       p.addText({ text: title, fontSize: 2, position: [0, 0.2], opacity: 0.7 });
    });
  });
}

By using $.parallel inside the group, we ensure both lines of text appear at the same time without advancing the group's internal flow pointer.

Why This Beats FFmpeg and Remotion

If you were doing this in FFmpeg, you would be wrestling with complex filter-graph strings and manual coordinate math for every frame. If you were using Remotion, you would be tied to a React runtime.

VideoFlow gives you the best of both worlds: a typed, developer-friendly API that compiles to a portable VideoJSON. This JSON can be rendered identically in the browser via @videoflow/renderer-browser or on a server via @videoflow/renderer-server.

For a deeper look at how our transition engine handles these entries, check out our guide on The 27 Transitions: A Developer's Guide to Cinematic Code.

Get Started with Overlays

Ready to build your own? The fastest way to experiment with GroupLayers and ShapeLayers is in the VideoFlow Playground. You can tweak properties in real-time and see the 60fps live preview instantly.

• Explore the Docs for more layer types.
• Star the project on GitHub to support open-source video tooling.
• Check out our Examples for more complex layout patterns.

Whether you are building a social media bot or an enterprise video automation platform, mastering the GroupLayer is the key to building professional, maintainable video assets.