Skip to content
On this page

Page Templates

Boxes allows you to define pre-defined compositions of your Box Partials as page templates.

When creating a page, the user can choose a template from a list of available options. The Boxes defined in the template will automatically be added to the newly created page.

Defining a Page Template

To define a page template, you need to create a boxes.yaml file in your theme's root directory.

In the file, you can define a list of templates with their boxes. Each template requires to have at least a handle property.

# /themes/your-theme/boxes.yaml
-   name: Empty page
    handle: empty
    boxes: []

# A product page, the "hero" cannot be modified at all,
# the "intro" is locked in-place, but the data is
# modifiable by the user, see "Locking" below.
-   name: Product page
    handle: product
    - partial: hero
      locked: true
    - partial: intro
      locked: ['position', 'deletion']
    - partial: text

# This template has a special "context" defined. This means
# it will not be available in the Boxes Editor by default.
-   name: Blog
    handle: blog
    - blog
    - partial: blog-hero
      locked: true
    - partial: blog-header
      locked: true


You can lock Boxes in a template to prevent the user from modifying them (see example above).

There are the following options available:

  • position - The Box cannot be moved
  • deletion - The Box cannot be deleted
  • data - The Box cannot be modified

You can also set locked to true to lock all options.

Inserting References Since 3.0

In certain use-cases, you want to add a Reference to an existing Box on another page. The special built-in Boxes\Internal\Reference partial allows you to do this.

Use the following syntax to reference the partial my-partial on a page with the code my-page:

- name: Page with reference to an existing Box
  handle: reference
  - partial: 'Boxes\Internal\Reference@my-page:my-partial

Applying Page Templates when using Boxes in custom plugins

See the Usage in Plugins section for more information.