Directus Visual Editor: Complete Setup and Integration Guide

The Directus Visual Editor lets you edit content directly on your live website without bouncing between a CMS panel and a preview. This guide shows you how to enable it, wire it into Next.js, and troubleshoot the most common problems.

What Is the Directus Visual Editor?

The Directus Visual Editor is an in-place editing system that overlays on your front-end, letting content editors see and modify content exactly as it appears to users. Instead of filling out forms in a CMS dashboard and hoping the preview matches reality, the Visual Editor shows changes live.

It works differently from traditional headless CMS editing. Most headless setups separate your content panel from your front-end: edit in Contentful, preview in another window, publish, refresh the website. Directus Visual Editor collapses that gap. You load your Next.js page or Nuxt app, click the edit button, and change text, blocks, and media in place.

The editor supports inline text edits, drag-and-drop block reordering, and component replacement. Directus calls this "visual editing" -- it powers live preview mode in a way that feels native to your framework. Directus has 45 million downloads and 500,000 projects deployed, and the Visual Editor is built into the core product: it is not a paid add-on.

Directus runs on a 4.9/5 G2 rating and is SOC 2 Type II certified and GDPR compliant. The open-source nature means you can host it yourself or use managed services. The Visual Editor works with Next.js, Nuxt, Astro, and Svelte -- we will focus on Next.js here because it is the most common integration.

Prerequisites and Requirements

You need four things in place before enabling Visual Editor:

Directus version: Visual Editor ships with Directus 12.0.0 and later. If you are on an older version, upgrade first. Check your current version in the admin panel under Settings > About or by running directus -v if you are self-hosted.

Framework support: Your front-end must be built with Next.js, Nuxt, Astro, or Svelte. This guide assumes Next.js 13 or later. Visual Editor works with the App Router and Pages Router, though App Router is more common now.

The front-end library: You need the directus/visual-editing npm package. It is a small library (roughly 5 KB gzipped) that handles the communication between your Next.js app and the Directus admin panel. Install it via npm or yarn.

Directus API access: Your Next.js app must be able to reach your Directus instance over HTTPS. Visual Editor runs in the browser, so it calls Directus endpoints directly. If your API is behind authentication or rate limits, ensure the Visual Editor token has permission to read the collections you are editing.

Editor permissions: In your Directus admin panel, grant Visual Editing role permission to the users who should see the edit button. This is set per role under Access Control > Roles > (your role) > App Access > Visual Editing.

You do not need a commercial license. Visual Editor is included in the free tier and all paid plans.

How to Enable Visual Editor in Directus

Enabling Visual Editor takes five steps:

Step 1: Open Settings in Directus Admin

Log in to your Directus admin panel and navigate to Settings > Data Model > Collections. Find the collection you want to edit visually (for example, Pages or Posts).

Step 2: Configure the Collection for Visual Editing

In the collection settings, look for the "Allow Visual Editor" toggle. Turn it on. This tells Directus that items in this collection can be edited visually.

You can optionally set a "Display Template" -- a field that Directus uses to generate a preview title in the Visual Editor (for example, Title or Slug). This helps editors quickly identify which page they are editing.

Step 3: Set Up Permissions

Go to Access Control > Roles and select the role you want to grant editing access to. Under Permissions, find your collection and enable Create, Read, and Update. If you want to prevent deletions via Visual Editor, leave Delete unchecked.

Also under the same role, scroll down and enable the Visual Editing app access. Without this, the edit button will not appear even if collection permissions are set.

Step 4: Create an API Token (If Using Token-Based Auth)

If your Next.js app uses API tokens instead of session cookies, create a static token in Settings > Access Tokens. Assign it the role you just configured. Set an expiration date or leave it open (only do this in development; rotate tokens in production).

Copy the token and add it to your Next.js .env.local:

NEXT_PUBLIC_DIRECTUS_API_TOKEN=your_token_here

Step 5: Test the Admin Panel

Go back to the content module (e.g., Pages), open an item, and confirm you see an Edit Visually button. Click it -- it should open a new window pointing to your Next.js app. If the button does not appear, double-check that Visual Editing is enabled on the collection and the user role has Visual Editing app access.

Integrating with Next.js: Step-by-Step Setup

Once Visual Editor is enabled in Directus, you need to wire the front-end library into your Next.js app. This is where the live editing happens.

Step 1: Install the Visual Editing Library

In your Next.js project root, run:

npm install @directus/visual-editing

This package provides the hooks and context you need to connect Next.js to Directus Visual Editor.

Step 2: Wrap Your App with the Visual Editing Context

Open your app/layout.tsx (or pages/_app.tsx if using Pages Router). Import the library and wrap your app:

import { VisualEditing } from '@directus/visual-editing/next';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <VisualEditing />
      </body>
    </html>
  );
}

The VisualEditing component injects a small script that listens for edit events from the Directus admin panel. Place it at the end of the body so it does not block page load.

Step 3: Mark Editable Regions

In your page components, wrap any field that should be editable with the EditableRegion component:

import { EditableRegion } from '@directus/visual-editing/next';

export default function Page({ page }) {
  return (
    <div>
      <EditableRegion 
        collection="pages" 
        id={page.id} 
        field="title"
      >
        <h1>{page.title}</h1>
      </EditableRegion>
      
      <EditableRegion 
        collection="pages" 
        id={page.id} 
        field="content"
      >
        <p>{page.content}</p>
      </EditableRegion>
    </div>
  );
}

Each EditableRegion maps to a field in your Directus collection. When an editor clicks on the region, Directus opens an inline editor or form for that field.

Step 4: Handle Draft Mode (Optional but Recommended)

In production, you typically do not want live editing on published pages -- only on drafts or unpublished versions. Next.js Draft Mode lets you preview draft content:

import { draftMode } from 'next/headers';

export default async function Page({ params }) {
  const { isEnabled } = draftMode();
  
  const page = await fetch(
    `${process.env.NEXT_PUBLIC_DIRECTUS_URL}/items/pages/${params.id}${
      isEnabled ? '?filter[_status][_eq]=draft' : ''
    }`
  );
  
  return (
    <div>
      {/* render page */}
    </div>
  );
}

This ensures only draft content is visually editable in preview mode.

Step 5: Test the Integration

Start your Next.js dev server:

npm run dev

Go to your Directus admin panel, open a page item, and click "Edit Visually." A new window should open to your local Next.js app, and you should see a blue outline around editable regions. Click one, make a change, and watch it update in real-time.

Advanced Configuration and Customization

Once basic setup works, you can extend Visual Editor.

Block-Based Editing: If your content uses repeatable blocks (e.g., a Hero, Section, CTA sequence), mark each block as editable:

{page.blocks.map((block) => (
  <EditableRegion
    key={block.id}
    collection="pages_blocks"
    id={block.id}
    field="type"
  >
    <Block type={block.type} data={block.data} />
  </EditableRegion>
))}

Editors can then reorder, add, and remove blocks directly on the page.

Custom Styling for Editable Regions: Add CSS to highlight editable areas:

[data-directus-editable] {
  position: relative;
  outline: 2px dashed blue;
  outline-offset: 4px;
}

This makes it obvious to editors which parts of the page are editable.

Conditional Editing: You can hide or disable editing based on user role or page state:

{isEditor && (
  <EditableRegion collection="pages" id={id} field="title">
    <h1>{title}</h1>
  </EditableRegion>
)}

Preview Links in Directus: In your Directus collection settings, configure a preview link so editors can jump straight to your Next.js preview URL from the admin panel.

Troubleshooting Common Issues

The Edit Visually button does not appear

Check three things: (1) Visual Editing is enabled on the collection (Settings > Data Model > Collections). (2) Your user role has Visual Editing app access (Access Control > Roles > (your role) > App Access). (3) The user is logged into Directus in a separate window or tab; Visual Editor requires an active Directus session.

Editable regions are not being highlighted

Ensure the <VisualEditing /> component is in your app layout and that you wrapped editable content with EditableRegion. Also check that @directus/visual-editing is installed and imported correctly.

Changes are not being saved

Verify that your API token or session has Create and Update permissions on the collection. If you see a permission error in the browser console, regenerate or rotate your API token and check the role permissions in Directus.

Visual Editor window is blank or shows a 404

Check that your NEXT_PUBLIC_DIRECTUS_URL environment variable is set correctly in Next.js and that the URL matches your Directus instance. Also check that your Next.js dev server is running and accessible from the machine where you are opening Visual Editor.

Slow edits or long save delays

This typically happens if your Directus instance is far from your Next.js server or if the API is overloaded. Check network latency with the browser DevTools Network tab. If latency is high, consider using a faster datacenter or CDN. Also verify that Opsily's managed Directus hosting can help optimize performance if you are self-hosted.

Inline editing is not working for rich text fields

For markdown or rich text fields, Visual Editor shows a modal form instead of inline editing. This is expected behavior. Make sure the field type is set to Text in Directus; if it is set to a custom type, Visual Editor may not recognize it.

When NOT to Use Visual Editor

Visual Editor is powerful but not right for every scenario.

Static Sites: If your site is fully static and regenerates on content change, Visual Editor adds complexity for little benefit. A traditional CMS dashboard is simpler.

Teams Without Designers: Visual Editor assumes editors understand layout and design. If your team is non-technical and needs strict content templates, a form-based CMS (like Opsily's managed Directus hosting with strict schemas) works better.

Content-Heavy Sites: If you have thousands of pages and editors rarely need immediate visual feedback, the overhead of Visual Editor is not worth the cost. Batch editing in the dashboard is faster.

Highly Customized Components: If your components use complex props, context, or state, Visual Editor may not be able to edit all fields. You may end up maintaining both Visual Editor and a fallback dashboard anyway.

Compliance-Heavy Environments: Visual Editor works in-browser, which can complicate audit trails and approval workflows. If you need strict version control and sign-offs, use Directus workflows instead.

For these cases, stick with the traditional Directus admin panel or consider Directus alternatives like Contentful or Payload CMS.

Frequently Asked Questions

Is Directus a CMS?

Yes, Directus is a headless CMS with built-in database API, user roles, and content workflows. Unlike traditional CMSes, Directus does not generate pages for you; you build the front-end separately and pull content via API. This gives you full control over design and performance.

What does a visual editor do?

A visual editor lets you see and edit content as it appears on the live website, without switching between a CMS panel and a preview window. Directus Visual Editor shows your Next.js, Nuxt, Astro, or Svelte site with clickable regions that open inline forms or direct text editing for each field.

How much does Directus cost?

Directus is open-source and free to self-host. Directus Cloud offers managed hosting starting at $15/month for small projects. Enterprise support and advanced features are available at higher tiers. Visual Editor is included in all plans, including the free tier.

Is Directus free to use?

Yes. The Directus software itself is free and open-source under the Business Source License (convertible to GPL after three years). You pay only for hosting if you use Directus Cloud or a managed service.

How does Directus work?

Directus exposes your database as a REST and GraphQL API. You define collections (tables), fields (columns), and roles (permissions) in the admin panel. Your front-end app queries the API to fetch content. The Visual Editor overlays on your front-end to allow live editing without rebuilding the admin panel.

Does Visual Editor work with other frameworks besides Next.js?

Yes. Visual Editor officially supports Next.js, Nuxt, Astro, and Svelte. The setup is similar across frameworks: install the library, wrap your app, and mark editable regions. Each framework has slightly different syntax, but the core flow is the same.

Can I use Visual Editor in production?

Yes, but use Draft Mode or a separate preview URL. Visual Editor is most useful for staging or preview environments where only editors can see it. In production, lock editing behind authentication and consider using Directus Workflows to add approval steps before content goes live.

What if my front-end is not Next.js, Nuxt, Astro, or Svelte?

Visual Editor requires framework integration. If you use a custom framework or static site generator, you can still use Directus as a CMS, but visual editing is not available. You will use the traditional admin dashboard instead. For a comparison with other frameworks, see Directus vs. Payload CMS to understand the tradeoffs.

The Bottom Line

Directus Visual Editor collapses the gap between content editing and live preview. It is included in Directus for free, works with popular frameworks, and takes about 20 minutes to set up on an existing Next.js project. The real win is that non-technical editors see what they edit, which cuts back-and-forth revisions and errors.

Start with the five-step setup, test it locally, and expand to advanced features like block editing as your team needs them. If you are already using Directus or considering it, Visual Editor is worth the 15-line integration. If you need hands-off infrastructure and managed backups, try Opsily's managed Directus hosting -- we handle the ops so you focus on editing.