This guide covers everything you need to know to create and maintain themes for TallCMS.

php artisan make:theme "My Theme" --author="Your Name" --description="Theme description"
cd themes/my-theme
npm install && npm run build
cd ../..
php artisan theme:activate my-theme

New themes are automatically configured with all required dependencies and imports.

themes/your-theme/
├── theme.json                 # Theme metadata and configuration
├── package.json               # NPM dependencies
├── vite.config.js             # Vite build configuration
├── tailwind.config.js         # Tailwind CSS configuration
├── public/                    # Static assets (images, fonts)
│   ├── screenshot.png         # Theme screenshot (1200×900px recommended)
│   └── build/                 # Compiled assets (auto-generated)
└── resources/
    ├── views/                 # Blade templates
    │   ├── layouts/           # Layout overrides
    │   └── cms/blocks/        # Block template overrides
    ├── css/
    │   └── app.css            # Theme styles
    └── js/
        └── app.js             # Theme JavaScript

TallCMS includes native Alpine.js components for built-in blocks (contact forms, galleries, etc.). Themes must import these for native blocks to function.

New themes created with make:theme automatically include the required import. No action needed.

If your theme was created before core components were introduced, add this import to your theme's resources/js/app.js:

// TallCMS Core Components - Required for native blocks
import '../../../../resources/js/tallcms';

// Your theme-specific code below...

Then rebuild:

cd themes/your-theme
npm run build

Native blocks like the contact form will render HTML but won't be interactive. You'll see console errors like:

Alpine Expression Error: contactForm is not defined

Themes can override any template by creating files that mirror the main application structure.

1. themes/your-theme/resources/views/ (highest priority)
2. resources/views/ (fallback)

Define your color palette in theme.json:

{
  "tailwind": {
    "colors": {
      "primary": {
        "50": "#eff6ff",
        "500": "#3b82f6",
        "600": "#2563eb",
        "700": "#1d4ed8",
        "900": "#1e3a8a"
      }
    }
  }
}

Blocks use CSS custom properties for theme integration:

/* These are set by blocks automatically */
--block-heading-color
--block-text-color
--block-button-bg
--block-button-text

Access theme colors in Blade templates:

$textPresets = theme_text_presets();
$buttonPresets = theme_button_presets();
$colorPalette = theme_color_palette();

cd themes/your-theme
npm run dev

cd themes/your-theme
npm run build

Or from project root:

php artisan theme:build your-theme

Themes should implement these menu locations:

<x-menu location="header" style="horizontal" />
<x-menu location="footer" style="footer" />

# Activate a theme
php artisan theme:activate your-theme

# List available themes
php artisan theme:list

# Build before activating
php artisan theme:build your-theme
php artisan theme:activate your-theme

Symptom: Console errors like contactForm is not defined

Solution: Add the core components import to your theme's app.js:

import '../../../../resources/js/tallcms';

Solution: Rebuild theme assets:

cd themes/your-theme && npm run build

Solution: Clear theme cache:

php artisan theme:cache:clear

When upgrading TallCMS, rebuild your themes to pick up new core components:

cd themes/your-theme && npm run build