Skip to main content
An editor layout defines how the annotation interface is presented to labelers inside a Project. It controls what panels appear, where media is displayed, which classification fields are visible, and how those elements are arranged on screen. Every Project created from a template comes with a pre-configured layout. You can use it as-is or customize it to match your workflow.

​
Creating Custom Layouts

  1. Open your Project and go to Overview.
  2. Click Set up next to Custom layout in the left sidebar. The layout builder opens, showing the current layout and a palette of components on the left.

​
Layout Structure

A layout is a tree of containers and items.
  • Containers hold other containers or items. They arrange their children either horizontally (side by side) or vertically (stacked).
  • Items are the leaf nodes — they render a specific piece of UI, such as a media player or a classification field.
You build layouts by dragging components from the palette into the canvas and nesting them inside containers.

​
Edit Layout

  • Add a component: Drag a component from the palette and drop it onto the canvas. Drop zones appear as you drag to indicate where the component can be placed.
  • Move a component: Drag an existing component to a new position within the canvas.
  • Configure a component: Click a component to select it. Its configuration options appear in the panel on the right. Changes take effect immediately in the preview.
  • Remove a component: Select the component and click the delete icon in the configuration panel, or use the context menu on the canvas.
  • Edit as JSON: Toggle JSON editor to view and edit the layout as raw JSON. This is useful for copying layouts between Projects or making bulk changes. The editor validates the JSON structure on save.

​
Palette Components

  • Stack: A vertical container. Children are arranged top to bottom. Use a Stack as the top-level wrapper for most layouts, or to group related fields below the media player.
  • Columns: A horizontal container. Children are arranged left to right. Use Columns to place the media player and classification fields side by side.
  • Media: Renders the media player for the current task — image, video, audio, or document. Every layout should include exactly one Media component. You can configure:
    • Controls — full shows all playback controls; minimal shows only essential controls.
    • Autoloop — automatically loops video or audio when playback reaches the end.
  • Field: Renders a single classification field from the Project’s Ontology. Custom layouts only support global classifications. Frame-based classifications do not appear in the palette and cannot be added to a layout. When you add a Field component, you select which ontology classification it maps to. The display style depends on the field type:
    Field typeDisplay options
    Select (single choice)Radio buttons, Dropdown
    MultiselectChecklist, Dropdown
    NumberNumber input, Slider
    TextText area
    You can also mark a field as read-only, which displays its value but prevents labelers from editing it.
  • Multi-step: Renders a sequential step-by-step wizard. Each step contains its own set of fields. Use Multi-step for workflows where data must be captured in a specific order — for example, first annotating the front of a document, then the back.

​
Global and Frame-Based Classifications

Custom layouts only support global classifications. Global classifications apply to the entire data unit, while frame-based classifications apply to individual frames.
If your existing layout contains a frame-based classification and you attempt to remove the component that holds it, Encord displays a confirmation dialog before proceeding. Once removed, you cannot add the frame-based classification back to the layout — it will not appear in the palette.
When you remove a component containing a frame-based classification, Encord prompts you to confirm the action with the following warning:
“Custom layouts only support global classifications. If you remove this, you cannot add it back to the layout.”
Click Remove to confirm, or dismiss the dialog to keep the component in place.

​
Layout Validation

Before you can save a custom layout, Encord validates the configuration and surfaces any errors that would result in an incomplete or broken annotation experience. Encord checks for the following issues:
  • Empty containers — A Stack or Columns container that contains no children. Add at least one component to the container, or remove it from the layout.
  • Empty Multi-step steps — A step inside a Multi-step component that contains no fields. Add at least one field to the step, or remove the step.
  • Incomplete Slider configuration — A Slider field with no minimum or maximum value set. Both values are required before saving.
  • Missing required classifications — A classification marked as required in the Project ontology that has not been added to the layout. Every required classification must appear somewhere in the layout — either directly or inside a Multi-step step — before you can save.
Validation errors appear in the header of the layout builder. Click an error message to highlight the affected component in the canvas. Errors related to missing required classifications do not highlight a specific component, since the field has not yet been placed in the layout.
Encord blocks saving until all validation errors are resolved. Review each error message, make the necessary changes, and then save the layout.
  • To update your Project’s Ontology without leaving the layout builder, you can open the Ontology editor directly from the palette.
  • The Edit ontology button is only visible to users with an Admin or Team Manager role on the Project.