# Kerbs Theme

Source: https://kart.bnomei.com/docs/kerbs-theme
Updated: 2026-02-20T12:54:37+00:00
Summary: Kerbs is a Svelte5 shop frontend for Kirby Kart with Pico.css styling, CSS-based theme tweaks, layouts/blocks support, SEO-ready, easy setup.

## Stylable but not customizable

The Kirby Kart plugin includes a hardwired, JavaScript-based shop frontend called **Kerbs**. It is built with [Svelte 5](https://svelte.dev) and interfaces with the underlying Kart plugin through an [Inertia.js](https://inertiajs.com) adapter. This setup greatly simplifies using Kirby as a headless CMS with stateful PHP sessions. It uses [unlazy by Johann Schopplich](https://unlazy.byjohann.dev) to load images lazily. The theme's styling is based on [Pico.css](https://picocss.com), allowing you to modify fonts, colours, and other design aspects through CSS. On any template, you can choose not to use the theme and instead utilise Kirby directly, allowing you to pick features from the theme if desired, selectively.

You can take a look at the [Kerbs theme preview here](https://kerbs.bnomei.com).

**To summarise: You can select when to use the theme and how it looks, but you can not change the layout of the theme itself. However, you can use layouts and blocks on a few templates.**

## Setup

You will need to copy a few folders and files from the plugins folder into the root of your project. Some of them might overwrite files from the [PHP-based setup](https://kart.bnomei.com/docs/setup/prefabs).

- Copy `blueprints-kerbs/pages/default.yml` into `site/blueprints/pages`, which will allow pages with the `default` template to be rendered by Kerbs
- Copy all files in `templates-kerbs` into `site/templates`, which will make the theme render for each respective template
- Copy the `snippets/kerbs/layout.php` from the plugins folder as `site/snippets/kerbs/layout.php`, which will allow you to apply custom styles and optimise SEO
- Create content files for cart and account at `content/cart/cart.txt` and `content/account/account.txt`

## Kerbs

As you might have noticed when copying the templates for Kerbs, all of them only have a single line of code: `<?php kerbs();`. That is enough to map the Kirby [template](https://getkirby.com/docs/guide/templates/basics) to the [page component](https://inertiajs.com/pages) defined within the JS code. Under the hood, it will prepare a bunch of JSON data and render it with the `site/snippets/kerbs/layout.php` snippet. In most cases, the JS code will not fully render the HTML skeleton again, but only fetch the required JSON very efficiently. The Kerbs theme supports the following templates:

- account
- cart
- default
- home
- login
- order
- product
- products
- signup

## Layouts and Blocks

The Kerbs theme has full HTML output support for creating content with Kirby [layout](https://getkirby.com/docs/reference/panel/fields/layout) and [blocks](https://getkirby.com/docs/reference/panel/fields/blocks). Whatever HTML code your snippet for that block generates will be rendered in the frontend, which means custom blocks can extend the Kerbs theme.

The main use case for this is to create content pages like the imprint, privacy policy, and about pages using the `default` template. However, you can also use them to add content to the `account`, `home`, `product,` and `product` templates.

Path: site/blueprints/home.yml  
Code (yaml):  
```
title: Home

fields:
  layout:
    type: layout
    layouts:
      - "1/1"
      - "1/2, 1/2"
```

  
## Styling with CSS

The general look and feel of the theme is defined by [Pico.css](https://picocss.com/docs). You select, download, and reference one of the [prebuilt CSS file versions](https://picocss.com/docs/version-picker) (regular with classes, no conditional styling)—like `pico.pumpkin.min.css` in the HTML head. You can load any other CSS/JS files you might need and adjust the [various CSS variables](https://picocss.com/docs/css-variables). I suggest using self-hosted fonts and CSS/JS whenever possible for better performance, security, and data protection. Payment provider assets should only be referenced from their servers.

You can style these with custom CSS rules when a template renders layouts and blocks.

Path: assets/css/templates/home.css  
Code (css):  
```
.kerbs-layouts {
  .kerbs-layout {
    .kerbs-column[data-span="12"] {
      .kerbs-blocks {
        .kerbs-block[data-type="text"] {
          color: #B4DA55;
        }
      }
    }
  }
}
```

  
## SEO

The Kerbs theme will render the HTML head, JSON data, and JS app for each regular HTML request. Meaning you can output meta tags optimised for SEO either manually or with the help of [plugins](https://plugins.getkirby.com/topics/seo). The Kerbs theme has a minimalistic `seo/head` snippet built in which will automatically be overwritten if you use the [popular SEO plugin from Tobias Möritz](https://plugins.getkirby.com/tobimori/seo).

## HTML layout skeleton

You copied the HTML layout skeleton for the Kerbs theme during setup as described above. You can customize it fully as needed.

The code by the plugin also automatically loads CSS/JS [based on the current template](https://getkirby.com/docs/reference/templates/helpers/css#example__autoloading-template-specific-css-files).

Path: site/snippets/kerbs/layout.php  
Code (php):  
```

<html lang="<?= kirby()->language()?->code() ?? 'en' ?>">
<head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <?php snippet('seo/head'); ?>
    <style>
        @font-face {
            font-family: "InterVariable";
            font-style: normal;
            font-weight: 100 900;
            font-display: block;
            src: url('/assets/fonts/InterVariable.woff2') format("woff2");
        }
        body {
            overflow-y: scroll;
            font-family: "InterVariable", sans-serif;
            --pico-font-family-sans-serif: "InterVariable", sans-serif;
        }
    </style>
    <?= css('assets/css/pico.pumpkin.min.css') ?>
    <?= css('@auto') ?>
    <?= js('@auto') ?>
    <?php if (kart()->option('turnstile.sitekey')) { ?><script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script><?php } ?>
</head>
<body>
<?= $slot ?>
<?php snippet('seo/schemas'); ?>
</body>
</html>
```

  
## Footer

- All listed pages on the root level will appear in the footer's left column.
- The centre column lists all categories.
- The `$site->copyright()->kirbytext()` will set the text of the right column.

## Thumbs &amp; Srcsets

The Kerbs theme uses the `default` and `blurred` **presets** as well as the `default` **srcset** to generate the images it needs. You can [adjust their configuration](https://getkirby.com/docs/reference/system/options/thumbs) to suite your needs.

Path: site/config/config.php  
Code (php):  
```
<?php

return [
   'thumbs' => [
        'presets' => [
            'default' => ['width' => 1024, 'quality' => 80],
            'blurred' => ['width' => 42, 'blur' => true],
        ],
        'srcsets' => [
            'default' => [300, 800, 1024],
        ],
    ],
    // other options...
];
```

  
## Future Updates

The Kerbs theme is tightly connected to the Kirby Kart plugin itself. Changes or additions to the plugin will require adjustments to the theme. If you use the theme, you accept that the layout of templates, features, or the rendered HTML output might change.   
Any significant changes will be documented in the [changelog](https://kart.bnomei.com/changelog).

## Source code of the Kerbs theme

The Kerbs theme's source code is not publicly available. You can [hire me](mailto:kart@bnomei.com) to build you a custom, hardwired version of the theme or [request a quote](mailto:kart@bnomei.com) for access to the full Svelte-5-based source code.

Since the Inertia.js adapter (`snippets/kerbs/inertia.php`) and the JSON data generators (`->toKerbs()`) are included in the Kirby Kart plugin, you can build your theme on top of that interface with whatever Inertia.js-compatible JS framework you want. That is easier than setting up a fully custom [headless interface](https://kart.bnomei.com/docs/forms/headless-and-hateoas) yourself, especially regarding the authentication of users.

## Troubleshooting

- Kerbs does not ship CSS and fonts. You need to download a PicoCSS theme and font files and point to it in `site/snippets/kerbs/layout.php`
- Kerbs has no logo itself. You need to provide `/assets/logo.svg`
- Products, categories and tags not showing up? If you just created the products via the `/kart` [local demo](https://kart.bnomei.com/docs/setup/localhost-demo) you might need to manually delete the Kirby `cache` folder once.

## Screenshots

![](https://kart.bnomei.com/media/pages/media/9e0a49ce22-1746706066/kerbs-products-1920x.webp)  
![](https://kart.bnomei.com/media/pages/media/315e7e784b-1746706066/kerbs-product-1920x.webp)  
![](https://kart.bnomei.com/media/pages/media/d7fdc53cc7-1746706066/kerbs-checkout-1920x.webp)  
![](https://kart.bnomei.com/media/pages/media/6166641ddb-1746706066/kerbs-order-1920x.webp)  
</body></html>