Skip to main content

Wagtail previews in headless mode.

Project description

Wagtail Headless Preview


Install using pip:

pip install wagtail-headless-preview

After installing the module, add wagtail_headless_preview to installed apps in your settings file:



then configure the preview client URL using the HEADLESS_PREVIEW_CLIENT_URLS setting.

For single site, the configuration should look like:

    'default': 'http://localhost:8020/',

For a multi-site setup, add each site as a separate entry:

    'default': 'http://localhost:8020/',
    '': 'http://localhost:8020/',
    '': 'http://localhost:8021/',


Add HeadlessPreviewMixin to your page class:

from wagtail_headless_preview.models import HeadlessPreviewMixin

class MyWonderfulPage(HeadlessPreviewMixin, Page):

How do I access preview content?

It depends on your project.

For a quick test:

  • Add wagtail.api.v2 to the installed apps:

  • Register the the API URLs so Django can route requests into the API:

from .api import api_router

urlpatterns = [
    path('api/v2/', api_router.urls),
    # Ensure that the api_router line appears above the default Wagtail page serving route
    path('', include(wagtail_urls)),
  • create an file in your project directory:
from django.contrib.contenttypes.models import ContentType

from wagtail.api.v2.endpoints import PagesAPIEndpoint
from wagtail.api.v2.router import WagtailAPIRouter

from wagtail_headless_preview.models import PagePreview
from rest_framework.response import Response

# Create the router. "wagtailapi" is the URL namespace
api_router = WagtailAPIRouter('wagtailapi')

class PagePreviewAPIEndpoint(PagesAPIEndpoint):
    known_query_parameters = PagesAPIEndpoint.known_query_parameters.union(['content_type', 'token'])

    def listing_view(self, request):
        page = self.get_object()
        serializer = self.get_serializer(page)
        return Response(

    def detail_view(self, request, pk):
        page = self.get_object()
        serializer = self.get_serializer(page)
        return Response(

    def get_object(self):
        app_label, model = self.request.GET['content_type'].split('.')
        content_type = ContentType.objects.get(app_label=app_label, model=model)

        page_preview = PagePreview.objects.get(content_type=content_type, token=self.request.GET['token'])
        page = page_preview.as_page()
        if not
            # fake primary key to stop API URL routing from complaining
   = 0

        return page

api_router.register_endpoint('page_preview', PagePreviewAPIEndpoint)

For further details, refer to the Wagtail API v2 Configuration Guide

  • Next, add a client/index.html file in your project root:
<!DOCTYPE html>
        function go() {
            var querystring =^\?/, '');
            var params = {};
            querystring.replace(/([^=&]+)=([^&]*)/g, function(m, key, value) {
                params[decodeURIComponent(key)] = decodeURIComponent(value);

            var apiUrl = 'http://localhost:8000/api/v2/page_preview/1/?content_type=' + encodeURIComponent(params['content_type']) + '&token=' + encodeURIComponent(params['token']) + '&format=json';
            fetch(apiUrl).then(function(response) {
                response.text().then(function(text) {
                    document.body.innerText = text;
<body onload="go()"></body>
  • Install django-cors-headers: pip install django-cors-headers
  • Add to your settings file
CORS_URLS_REGEX = r'^/api/v2/'
  • Start up your site as normal: ./ runserver 0:8000
  • Set up client/index.html to be served at http://localhost:8020/ - this can be done by running python3 -m http.server 8020 from inside the client directory
  • Edit (or created) and preview a page that uses HeadlessPreviewMixin
  • The preview page should now show you the API response for the preview


  • Matthew Westcott (@gasman), initial proof of concept
  • Karl Hobley (@kaedroho), improvements

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

wagtail-headless-preview-0.0.4.tar.gz (6.3 kB view hashes)

Uploaded Source

Built Distribution

wagtail_headless_preview-0.0.4-py2-none-any.whl (7.4 kB view hashes)

Uploaded Python 2

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page