---
title: "layout"

doc_type: static
doc_category: static
doc_version: v20270301
source_url:
  html: 'https://developer.shopline.com/docs/online-store-3-0-themes/theme-structure/layout'
  md: 'https://developer.shopline.com/docs/online-store-3-0-themes/theme-structure/layout.md'
---
# layout

The `layout` directory contains the theme's layout files, which define the basic framework of pages and enable consistent management of page structures and styles.

Layout files must include the following placeholders:

-   **header**: the header section
    
-   **layout**: the page content
    
-   **footer**: the footer section
    

These placeholders are used to inject global scripts, such as JavaScript and CSS files, and render page contents.

Additionally, you can add custom HTML, CSS, or JavaScript in the layout files to apply the same changes across multiple pages.

* * *

## Directory structure{#kVCc9}

The default layout file structure of the [Bottle theme](https://developer.shopline.com/docs/online-store-3-0-themes/bottle.md?lang=en) is as follows:

```bash
layout
├── gift_card.html   # Layout file for the gift card page
├── password.html    # Layout file for the password page
├── proofing.html    # Layout file for the store closing page 
└── theme.html       # Default layout page (automatically applied to all pages for which layout files are not specified)
```

You can also create custom layout files. The following shows an example:

```bash
layout
├── gift_card.html   		
├── password.html    		
├── proofing.html    		
├── theme.html       		
└── custom_layout.html	# Custom layout file
```

* * *

## Layout file specification{#iu7aO}

### File structure{#HnqnF}

The layout file must include the header, layout, and footer placeholders. You need to reference these placeholders through the [content](https://developer.shopline.com/docs/sline/tag/content.md) tag. You can also include custom code in the file to achieve a synchronized application across multiple page templates.

The following shows a basic layout file example:

```html
<!DOCTYPE html>
<html>
<head>
  {{#content "header" /}}  <!-- The header placeholder -->
</head>
<body>
  {{#content "layout" /}}  <!-- The content placeholder -->
  
  {{#content "footer" /}}  <!-- The footer placeholder -->
  
  <!-- The custom script example -->
  <script>
    console.log('This is a custom script');
  </script>
</body>
</html>
```

### Required placeholders{#B31GU}

The following table explains the required placeholders in the layout file.

<table>
  <colgroup>
    <col/>
    <col/>
    <col/>
  </colgroup>
  <tbody>
    <tr>
      <th>
        <p><strong>Placeholder</strong></p>
      </th>
      <th>
        <p><strong>Injected content types</strong></p>
      </th>
      <th>
        <p><strong>Typical use cases</strong></p>
      </th>
    </tr>
    <tr>
      <td>
        header
      </td>
      <td>
        <ul>
          <li>Common scripts</li>
          <li>Styles</li>
          <li>App resources</li>
        </ul>
      </td>
      <td>
        <ul>
          <li>Theme event SDK</li>
          <li>Custom code app</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td>
        layout
      </td>
      <td>
        <ul>
          <li>Page body HTML</li>
        </ul>
      </td>
      <td>
        <ul>
          <li>Page details</li>
          <li>Cart page template</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td>
        footer
      </td>
      <td>
        <ul>
          <li>Common scripts</li>
          <li>Styles</li>
          <li>App resources</li>
        </ul>
      </td>
      <td>
        <ul>
          <li>Event tracking</li>
          <li>Performance monitoring scripts</li>
        </ul>
      </td>
    </tr>
  </tbody>
</table>
* * *

## Layout application{#zFsQD}

### JSON template{#sIEhp}

In a [JSON template](https://developer.shopline.com/docs/online-store-3-0-themes/theme-structure/templates.md?lang=en#YWmjr), use the `layout` field to specify the layout file you want to use for the page.

The following example shows the use of the `password.html` layout file for the store's password protection page:

```json
// In templates/password.json, specify the layout field.

{
  "layout": "password",  //Specify layout/password.html
  "sections": {
    "main-password": {
      "type": "password"
    }
  },
  "order": ["main-password"]
}
```

### HTML template{#ptRdc}

In an [HTML template](https://developer.shopline.com/docs/online-store-3-0-themes/theme-structure/templates.md?lang=en#qbWua), use the [layout](https://developer.shopline.com/docs/sline/tag/layout.md) tag to specify the layout file you want to use for the page.

The following example shows the use of the `proofing.html` layout file for the store closing page:

```html
<!-- In templates/proofing.html, specify the layout field. --> 

{{#layout "proofing" /}}  <!-- Explicitly refer to layout/proofing.html --> 

<div class="page-width stage__proofing">
  <div>
    <img width="240" height="160" src="{{`images/image-store-close.png` | asset_url()}}" alt="close the store" />
    ...
  </div>
</div>
```
> **Caution**
>
> When you do not specify a specific layout file for a page template, `layout/theme.html` is automatically used as the default.

* * *

## Best practices{#StOFh}

### Enhance the default layout{#LddwD}

Set responsive viewport `<meta>` tags in the default layout file `theme.html`, as shown in the following example:

```html
<!DOCTYPE html>
<html>
<head>
  <!-- Customize the meta tag --> 
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
  {{#content "header" /}}
</head>
<body>
  {{#content "layout" /}}
  
  {{#content "footer" /}}
</body>
</html>
```

### Design for scalability{#KpYaa}

Leverage CSS class names to differentiate layout types, thereby optimizing global style management. The following shows an example:

```html
<!DOCTYPE html>
<html>
<head>
  {{#content "header" /}}
</head>
<body class="layout-{{ layout.name }}">	<!-- Customized class -->
  {{#content "layout" /}}
  
  {{#content "footer" /}}
</body>
</html>
```