Reusable UI components – A journey from React to Wagtail

This is Ben Dickinson and I’s joint Wagtail Space US 2020 talk about pattern libraries at Torchbox, introducing django-pattern-library.

Slides: Wagtail Space US 2020 - Reusable UI components – A journey from React to Wagtail

Pattern libraries as a methodology

Atomic Design

Pattern Lab


A paradigm shift

  • Component-driven UIs
  • Functional programming for UIs
  • Not a template language

What makes React good in practice

  • Nice developer experience
  • Reusable components
  • Maintainable, testable code
  • Component-driven development with Storybook

Pattern libraries at Torchbox

The codified interface between front-end and back-end work

  • Clarifies responsibilities, separates concerns, both in code, and as members of a development team
  • If needed, makes it possible for front-end developers to work on pages and block templates before the models are done
  • Encourages code reuse – defining independent UI components, easy to port to other projects

Why develop another pattern library tool?


  • Most of our projects are not API-driven React SPAs - they’re vanilla Django/Wagtail
  • Django has a proprietary template language
  • Translating non-Django templates from a pattern library is time-consuming and error-prone
  • Duplicating templates is a maintenance burden and often leads to divergence

More challenges!

  • Template tags are great, but are discouraged by using a pattern library that doesn’t support them
  • Tags often depend on the database (e.g. include_block foo)
  • Visual testing requires time-consuming manual setup
  • Django’s native testing tools are inadequate for visual testing - especially cross-browser

Pattern Lab goes Django!

pip install django-pattern-library


  • Component playground for Django template partials
  • Mock template context from YAML files
  • Template documentation in markdown
  • Mock out template tags (both built-in and user-defined tags)


  • No duplication of templates - the pattern library uses the real templates
  • All components can be viewed in one place
  • Easier visual testing
  • No need for content in the DB
  • Front-end development can happen before the models are ready

Known issues

  • Documentation is good but could be much better
  • Context merging is fragile and requires some repetition in YAML files
  • Template tag mocking is not flexible enough
  • No support for mocking filters yet
  • Richer objects are fiddly to mock (e.g. ``)

Demo time!

First demo

Second demo


Takeaways 🌈

Why we recommend this approach

  • As a methodology: speeds up the process for medium to large sites
  • Reusable components: Encourages code reuse and UI consistency across the site
  • Testing opportunities: Manual “unit tests” for UI components, & opportunities for automated visual regression / E2E / accessibility tests

Ready to use

Ready for contributions 😬

Backlog for the next three months: github.com/torchbox/django-pattern-library/projects/3

Thank you!

Thank you to Dan, Tom, William, Nick for helping us rehearse!