Builder

Builder.io is a visual headless CMS and page builder that allows you to create and manage content visually while maintaining full control over your codebase. Builder provides deep visual customization — including fonts, colors, layout, and spacing — but it is also built around code-backed, reusable components. At Terra, we use it for Descript website.

This guide explains how Builder.io works, its main features, and the best practices we follow when working with it.

---

Overview

Builder.io is designed around visual editing with code-backed components.

Customization and Components

One important concept to understand early is that visual changes are page-specific by default. This makes Builder very flexible, but it also means that component repetition across multiple pages must be handled intentionally to avoid inconsistencies.

Unlike traditional page builders, Builder.io:

• integrates directly with your codebase through SDKs
• allows custom React/Vue components to be used in the visual editor
• supports programmatic data fetching and dynamic content
• maintains separation between content and code

---

Symbols: Managing Reusable Components

Builder provides Symbols (identified by the purple highlight in the Layers sidebar). You should create symbols whenever a component is repeated across multiple pages.

Symbols allow you to:

• Reuse components across multiple pages
• Apply changes globally from a single source
• Keep visual consistency at scale

Key concepts:

• Edit Symbol: Changes are propagated to all instances across pages
• Detach Symbol: Breaks the connection, making the component page-specific

---

Publishing and Environments

Builder is directly connected to the production environment for Descript.

Publishing behavior:

• Existing pages: Changes are published directly to descript.com
• New pages: Must be manually published by the client

---

Assets and Custom Code

Asset Management

• Images are stored and managed through the Asset Library / Media Gallery
• Assets can be reused across pages and components

Custom Code

Builder allows the use of custom code for advanced or specific functionalities, including:

• Sliders and interactive components
• External libraries
• Custom CSS and JavaScript (accessible via the Database icon -right sidebar)

---

Breakpoints and Resize Events

In Builder, Breakpoints do not refresh automatically and Resize events are unreliable.

Common issues:

• A component with desktop hover behavior may keep the same behavior when switching to mobile without a page refresh
• Responsive logic is only applied after a manual refresh

---

---

Best practices

• Create Symbols for components repeated across multiple pages.
• Always check if a component is a Symbol before editing it.
• Use Detach Symbol only when a page-specific variation is needed.
• Review the Asset Library before uploading new images.
• Remember that changes to existing pages publish directly to production.
• Always refresh the page when testing responsive behavior.
• Be cautious with custom code that relies on resize or breakpoint events.
• Test both desktop and mobile views after making changes.