Usage

This version is deprecated, the versions 3/4 should be used instead.

Create the folder themes/{name}
Create the class themes/{name}/Theme.php, an example here, make sure it has a namespace
Create the folder themes/{name}/templates

That's enough to define a theme that you can enable in the backend.

Composer

If you bundle a theme into a composer package, 2 things are required :

• Your composer.json must have the type craft-theme.
• Your composer.json must have a parameter handle in the extra section. If this is not present, your theme will have its package name as handle.

Assuming your package is accessible through composer, you can require it like any other package, it will be installed in the themes folder.

You will need to empty the themes cache after creating a new theme, through the backend or with php craft clear-caches/themes-cache

See an example

Partial themes

A partial theme will not be available to select in the backend, but it can be inherited from. Define a partial theme with the method isPartial(): bool of the main class.

Asset bundles

Asset bundles can be defined in your theme class, in the $assetBundles property, it's an array indexed by the url path :

[
    '*' => [
        CommonAssets::class
    ],
    'blog' => [
        BlogAsset::class
    ]
]

Bundle assets will be registered automatically, the '*' will be registered on every page.

By default, parent themes bundles will also be registered. This can be disabled with the property $inheritsAssetBundles of your theme class.

Inheritance

Themes can extend each other with the property $extends of their Theme class.

Templates

Templates are inherited, that's the whole point isn't it ?

So if you call a template that isn't defined in your theme but exist in a parent theme, the parent template will be loaded.

Assets (images, fonts, etc)

Assets can be inherited through the twig function theme_url.
If you have an image.jpg defined in your theme in the images folder, you can publish it with theme_url('images/image.jpg')

If you require an asset and the file is not present in your theme, it will look in the parent theme (if defined).

This inheritance can be disabled with the property $inheritsAssets of your theme class.

Root template folder

It is recommended to not use the root templates folder when using themes, if some templates are defined both in this folder and in a theme, the root templates folder will take precedence.

A theme cannot override templates that have a namespace (ie other plugin templates), unless they register their templates roots with the '' (empty string) key.