Themes

• Introduction
• Key ideas
  • A theme is a package
  • A theme names its engine
  • Themes can inherit
  • The theme picks the page component
• Which theme is active
• Next

Introduction

A theme renders the public site. Modules collect the page data; the active theme turns it into HTML. A site can have many themes installed, but only one is active at a time — exactly like WordPress.

kitloom ships three themes you can use as they are or as a starting point. Each one requires its engine, so installing the theme installs the engine too:

Theme	Package	Engine
Portfolio	kitloom/portfolio-theme	Inertia + Vue (kitloom/inertia)
BladeTheme	kitloom/blade-theme	Blade (kitloom/blade) — no build step, no JavaScript framework
Marketplace	kitloom/marketplace-theme	Blade (kitloom/blade) — a shop on kitloom/shop, prebuilt Tailwind CSS

Key ideas

A theme is a package

A theme lives either in your application's themes/{Theme} directory or in its own Composer package in vendor/. A packaged theme declares itself in its composer.json, so installing it is a plain composer require. See Writing a Theme.

A theme names its engine

The engine is what renders the page:

Engine	Package	Theme provides
inertia	kitloom/inertia	.vue page components in resources/js/Pages
blade	kitloom/blade	Blade templates in resources/views

The engine is chosen by the active theme, not by which packages are installed. One application can have a Vue theme and a Blade theme side by side; whichever is active decides. With no active theme, every page is returned as JSON — a headless site.

Themes can inherit

A child theme names a base theme. Whatever the child does not have — page components, styles, a service provider — comes from the base. Language or regional copies of a site are the typical use. The base never lists its children. See Child Themes.

The theme picks the page component

For each page kitloom decides which component (or template) of the theme renders it: a post of type book → Pages/Book/Index, a genre term → Category/Genre/Index, with sensible fallbacks. See Page Components.

Which theme is active

The active theme is resolved on every request in this order:

1. The theme selected on Appearance → Themes — the current_theme option in the options table.
2. The default theme — APP_THEME in .env (kitloom-themes.default), while nothing is selected yet.
3. The fallback theme — kitloom-themes.fallback.

A theme is only used if it is installed in this environment: declared, and its directory exists. The selection is cached for an hour and reset when it changes from the admin.

A theme deactivated on the Themes screen is different from "nothing selected": the option is kept, empty, and the site uses no theme at all — neither the default nor the fallback. Every page is then returned as JSON, for a headless frontend.

The admin screens:

Panel	Where
Filament	Appearance → Themes (kitloom/themes-filament)
Nova	Appearance → Themes (kitloom/themes-nova); the Current Theme field also stays in Settings → General

Each theme is a card with its name, description, version, authors, engine, base theme and screenshot. The Activate button:

• refuses a Vue theme that is not built yet (run npm run build:themes);
• runs the theme's pending migrations first — if they fail, the theme is not switched;
• switches the theme for the next request.

The active theme's card has Deactivate instead. It asks for confirmation, then switches the theme off: the site serves its pages as JSON until a theme is activated again, and the screen shows a notice above the cards.

Next

• Installing Themes
• Writing a Theme