---
title: "Backend layout"
manual: "TYPO3 Explained"
version: "14.3"
permalink: "https://docs.typo3.org/permalink/t3coreapi:be-layout@14.3"
source: "ApiOverview/Backend/BackendLayout.rst"
rendered: "2026-09-20T16:07:38+00:00"
---

# Backend layout {#be-layout}

Backend layouts can be defined as database records or via [page TSconfig](https://docs.typo3.org/m/typo3/reference-typoscript/14.3/en-us/PageTsconfig/Index.html#pagetsconfig).
Page TSconfig should be preferred as it can be stored in the file system and
be kept under version control.

## Backend layout video {#be-layout-video}

Benjamin Kott: How to implement frontend layouts in TYPO3 using backend layouts

[Watch this video on YouTube](https://www.youtube.com/watch?v=RoHaeo4fq34)

## Backend layout configuration {#be-layout-info-module}

The backend layout to be used can be configurated for each page and/or a pages'
subpages in the **Page properties > Appearance**. Multiple backend
layouts are available if an
[extension providing backend layouts](https://docs.typo3.org/permalink/t3coreapi:be-layout-extensions@14.3) is installed or
backend layouts have been
[defined as records or page TSconfig](https://docs.typo3.org/permalink/t3coreapi:be-layout-definition@14.3).

![](../../Images/ManualScreenshots/BackendLayouts/PagePropertiesAppearance.png)

<!-- TODO: no Markdown rendering for "versionchanged" -->

The main module web has been renamed to content.
See Feature: #107628 - Improved backend module naming and structure

The **Content > Status** module gives an overview of the backend layouts configured or
inherited from a parent page at
**Content > Status > Pagetree overview > Type: Layouts**:

![](../../Images/ManualScreenshots/BackendLayouts/PageTreeLayoutOverview.png)

## Backend layout definition {#be-layout-definition}

Backend layouts can be configured either as "backend layout" record in a sysfolder or as page TSconfig entry in
`mod.web_layout.BackendLayouts`. Each layout will be saved with a key. The "backend layout" records are
using their uid as a key, therefore layouts defined via page TSconfig should use a non-numeric string key. It is a good
practice to use a descriptive name as key.

The entries title and icon are being used to display the backend layout options in the page properties.

The overall grid size will be defined by `config.backend_layout.colCount` and `rowCount`.
Additional rows in the `rows` array and additional columns in the each rows `columns` section
will be ignored when they are greater than `rowCount` or `colCount` respectively.

Each column position can span several columns and or several rows. Each column position must have a distinct number
between 0 and n. It is best practice to always assign "0" to the main column if there is such a thing as a
main column. Multiple backend layouts that contain similar parts, i.e. header, footer, aside, ...  should each have
assigned the same number within one project. This leads to a uniform position of the content, which makes it more clear
for further use.

For usage with the [page-content data processor](https://docs.typo3.org/m/typo3/reference-typoscript/14.3/en-us/DataProcessing/PageContentFetchingProcessor.html#PageContentFetchingProcessor), an identifier string must
be assigned to each column. The default backend layout definition uses `identifier = main` for column `0`.

## Backend layout simple example {#be-layout-simple-example}

The following page TSconfig example creates a simple backend layout consisting of two rows and just one column.

**EXT:my_extension/Configuration/page.tsconfig**

```typoscript
mod {
  web_layout {
    BackendLayouts {
      exampleKey {
        title = Example
        config {
          backend_layout {
            colCount = 1
            rowCount = 2
            rows {
              1 {
                columns {
                  1 {
                    identifier = border
                    name = frontend.ttc:colPos.I.3
                    allowedContentTypes = html, text, ...
                    colPos = 3
                    colspan = 1
                  }
                }
              }
              2 {
                columns {
                  1 {
                    identifier = main
                    name = Main
                    colPos = 0
                    colspan = 1
                  }
                }
              }
            }
          }
        }
        icon = EXT:example_extension/Resources/Public/Images/BackendLayouts/default.gif
      }
    }
  }
}

```

## Backend layout advanced example {#be-layout-advanced-example}

The following page TSconfig example creates a 3x3 backend layout with 5 column position sections in total. The topmost
row (here called "header") spans all 3 columns. There is an "aside" spanning two rows on the right.

**EXT:my_extension/Configuration/page.tsconfig**

```typoscript
mod.web_layout.BackendLayouts {
  exampleKey {
    title = Example
    icon = EXT:example_extension/Resources/Public/Images/BackendLayouts/default.gif
    config {
      backend_layout {
        colCount = 3
        rowCount = 3
        rows {
          1 {
            columns {
              1 {
                identifier = header
                name = Header
                colspan = 3
                colPos = 1
              }
            }
          }
          2 {
            columns {
              1 {
                identifier = main
                name = Main
                colspan = 2
                colPos = 0
              }
              2 {
                identifier = aside
                name = Aside
                rowspan = 2
                colPos = 2
              }
            }
          }
          3 {
            columns {
              1 {
                identifier = left
                name = Main Left
                colPos = 5
              }
              2 {
                identifier = right
                name = Main Right
                colPos = 6
              }
            }
          }
        }
      }
    }
  }
}

```

## Output of a backend layout in the frontend {#be-layout-frontend}

The backend layout to be used on a certain page gets determined either by the backend layout being chosen directly and
stored in the pages field "backend_layout" or by the field "backend_layout_next_level" of a parent page up the rootline.

To avoid complex TypoScript for integrators, the handling of backend layouts has
been simplified for the frontend.

To get the correct backend layout, the following TypoScript code can be used:

**EXT:my_sitepackage/Configuration/Sets/MySitepackage/setup.typoscript**

```typoscript
page.10 = FLUIDTEMPLATE
page.10 {
  file.stdWrap.cObject = CASE
  file.stdWrap.cObject {
    key.data = pagelayout

    default = TEXT
    default.value = EXT:my_sitepackage/Resources/Private/Templates/Home.fluid.html

    3 = TEXT
    3.value = EXT:my_sitepackage/Resources/Private/Templates/1-col.fluid.html

    4 = TEXT
    4.value = EXT:my_sitepackage/Resources/Private/Templates/2-col.fluid.html
  }
}

```

Using  `data = pagelayout` is the same as using as

```typoscript
field = backend_layout
ifEmpty.data = levelfield:-2,backend_layout_next_level,slide
ifEmpty.ifEmpty = default
```

In the Fluid template the column positions can be accessed now via content mapping as described here
[Display the content elements on your page](https://docs.typo3.org/m/typo3/tutorial-sitepackage/14.3/en-us/ContentMapping/Index.html#content-mapping).

## Reference implementations of backend layouts {#be-layout-reference-implementations}

The extension [`bk2k/bootstrap-package`](https://packagist.org/packages/bk2k/bootstrap-package) ships several
[Backend layouts](https://github.com/benjaminkott/bootstrap_package/tree/1b00a01e362d2460af92f754ee10e507edb70568/Configuration/TsConfig/Page/Mod/WebLayout/BackendLayouts)
as well as an example configuration of how to include frontend templates for backend layouts (see its
[setup.typoscript](https://github.com/benjaminkott/bootstrap_package/blob/1b00a01e362d2460af92f754ee10e507edb70568/Configuration/TypoScript/setup.typoscript#L99-L113))

## Extensions for backend layouts {#be-layout-extensions}

In many cases besides defining fixed backend layouts a more modular approach with the possibility of combining different
backend layouts and frontend layouts may be feasible. The extension
[`b13/container`](https://packagist.org/packages/b13/container)
integrates the grid layout concept also to regular content elements.

<!-- TODO: no Markdown rendering for "versionchanged" -->

Installing the extension ichhabrecht/content-defender for allowed
or disallowed content elements per column is no longer necessary. Backend
layout columns can now natively restrict content element types via
allowedContentTypes and disallowedContentTypes.
See Feature: #108623 - Allow content element restrictions per colPos.

## Backend layout providers {#backend-layout-providers}

<!-- TODO: no Markdown rendering for "versionchanged" -->

Backend layout providers are now autoconfigured once they implement the required
\TYPO3\CMS\Backend\View\BackendLayout\DataProviderInterface.The configuration via $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['BackendLayoutDataProvider']
has no effect anymore but can be kept until dropping TYPO3 v13 support.See Feature: #107784 - Autoconfigure backend layout data providers.

Backend layout data providers, classes implementing `\TYPO3\CMS\Backend\View\BackendLayout\DataProviderInterface`,
supply TYPO3 with the available backend layouts
and allow layout definitions to be loaded from different sources, such
as database records, Page TSconfig, or custom implementations.

They define which content areas editors can see and use in the
**Content > Layout** module.

**EXT:my_extension/Classes/DataProviders/MyLayoutDataProvider.php**

```php
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\DataProviders;

use TYPO3\CMS\Backend\View\BackendLayout\BackendLayout;
use TYPO3\CMS\Backend\View\BackendLayout\BackendLayoutCollection;
use TYPO3\CMS\Backend\View\BackendLayout\DataProviderContext;
use TYPO3\CMS\Backend\View\BackendLayout\DataProviderInterface;

final class MyLayoutDataProvider implements DataProviderInterface
{
  public function getIdentifier(): string
  {
    return 'my_provider';
  }

  public function addBackendLayouts(
    DataProviderContext $dataProviderContext,
    BackendLayoutCollection $backendLayoutCollection,
  ) {
    // TODO implement
  }

  /**
   * Gets a backend layout by (regular) identifier.
   *
   * @param string $identifier
   * @param int $pageId
   * @return BackendLayout|null
   */
  public function getBackendLayout($identifier, $pageId)
  {
    // TODO implement
  }
}

```

The TYPO3 Core provides the `DefaultDataProvider` and
the `PageTsBackendLayoutDataProvider`.

Third party extension [`fluidtypo3/flux`](https://packagist.org/packages/fluidtypo3/flux) implements, for example, its
own backend layout data provider.

### Manual service configuration {#backend-layout-providers-configuration}

If autoconfiguration is disabled, manually tag the service in
`Services.yaml`:

**EXT:my_extension/Configuration/Services.yaml**

```yaml
services:
  MyVendor\MyExtension\View\BackendLayout\MyLayoutDataProvider:
    tags:
      - name: page_layout.data_provider

```

### Backend layout provider ordering {#backend-layout-providers-ordering}

If you need to control the order in which providers are processed, use service
priorities in your `Services.yaml`:

**EXT:my_extension/Configuration/Services.yaml**

```yaml
services:
  MyVendor\MyExtension\View\BackendLayout\MyLayoutDataProvider:
    tags:
      - name: page_layout.data_provider
        priority: 100

```