UserSpice
Home / Installing and Creating Templates

Installing and Creating Templates

Templates control the look and feel of the front end of your UserSpice project. The default template ships Bootstrap 5, but UserSpice doesn't lock you in — build your pages with any CSS framework you like, or none at all. This page is part of the UserSpice Customization Guide.

  1. 01 Easiest path

    Install with Spice Shaker

    Spice Shaker is the preferred way to install official and curated community templates. Open it from the Admin Dashboard, pick Templates, and hit Go to browse what's available.

    • 1Spice Shaker → Templates → Go.
    • 2Click install on the template you want. Most have a Preview option, too.
    • 3Installing isn't activating. Go to Tools → Templates and click Activate.
  2. 02 No Shaker? No problem.

    Manual install

    If you can't (or don't want to) use Spice Shaker, you can grab template zips from the UserSpice Template List.

    • 1Download the template zip.
    • 2Unzip into usersc/templates/ — each template lives in its own subfolder.
    • 3Tools → Templates → Activate.
  3. 03 One-off override

    Use a different template on a single page

    Sometimes you need one page (a landing page, a print view, a docs page) to use a different template than the rest of the site. Set $template_override before you require init.php:

    <?php
$template_override = 'citrus';
require_once '../users/init.php';

    The string is the folder name in usersc/templates/. UserSpice will die() with a clear error if that folder doesn't exist, so typos are easy to spot.

  4. 04 Removing one

    Deleting a template

    Activate a different template first. If you delete the active template, UserSpice will look for bs5 as a fallback. If that's missing too, it walks usersc/templates/ alphabetically and activates the first valid template it finds. If nothing valid is left, the site won't load at all.

    Once a different template is active, just delete the folder: 

    rm -rf usersc/templates/your_template_name
  5. 05 Build your own

    Create your own template

    Don't edit the shipped templates directly. Updates will overwrite your changes. For most customization needs, the Customizing UserSpice Guide has a better answer — usually usersc/includes/head_tags.php (per-page CSS/JS) or usersc/includes/custom_functions.php (per-page PHP).

    If you genuinely need a new template, copy whichever shipped template is closest to what you want into a new folder under usersc/templates/ and edit from there. There's also a nocss template if you want to start from a blank slate.

    Heads up on navigation. The trickiest part of a custom template is the nav menu. If database-driven navigation gets in your way, file-based (hard-coded) nav is a perfectly fine choice — several shipped templates do exactly that.

  6. 06 Anatomy

    What's inside a template

    A template is just a folder of PHP partials and an info.xml. UserSpice loads them in this order on every page render:

    • header.php — opens <html>, loads CSS/JS
    • navigation.php — top nav (skipped if $hide_top_navigation = true)
    • container_open.php — wraps the page body
    • (your page content runs here)
    • container_close.php — closes the body wrapper
    • footer.php — closes </html>

    The rest of the folder:

    • info.xml — name, version, author (Spice Shaker reads this)
    • preview.php — what shows up under "Preview" in the templates UI
    • thumbnail.jpg — thumbnail in Spice Shaker / template list
    • assets/ — CSS, JS, fonts, images for the template

    Open usersc/templates/bs5/ to see a working example. It's the smallest of the shipped templates and the easiest to read top-to-bottom.