Customize and theme

Learn how to customize and theme Halfmoon to fit your needs.

Work in progress

This page is a work in progress. As we work to flesh out the concepts of customization and add examples, please go through the next section to get a quick gist of the whole thing. You can also go through the actual halfmoon.css file—the whole thing is fairly easy to understand, and rather self-explanatory.

How it works #

Halfmoon's customizability comes from the use of CSS variables. We employ a novel method for this: defining broadly scoped, root-level variables, which are then inherited by component-level variables. This means that you can change a handful of the root-level variables and have those changes propagate to individual components. For example, changing the root-level --bs-content-bg will change the background color of cards, modals, sidebar, and offcanvas components. This makes theming incredibly quick and easy.

This method also means that each core theme is very small in size, so you can add multiple ones to your site and let your users decide which one they want to use (similar to a dark mode preference). For reference, this documentation site loads in all three of the built-in core themes, and the additional CSS required for this comes in at only around 20KB unminified.

Core themes #

Halfmoon comes with the three following built-in core themes (with dark mode support for all three):

default — Classic, inspired by Apple HID.
modern — Like default, but with slightly more modern design sensibilities, particularly in dark mode.
elegant — Beautiful and classy, almost Tuftian.

You can find the CSS files within the /css/cores folder in the latest download release.

Core themes Usage #

The core themes are built using CSS variables, so you can have a system where the user is able to pick their preferred core theme during runtime (similar to a dark mode preference). Please note, we only support global usage of the core themes. You can implement the core themes in your site by following the steps below:

Include the CSS files for the core themes, so halfmoon.modern.css and halfmoon.elegant.css, or just include halfmoon.cores.css which combines the two. For the default core, no extra file is required (only halfmoon.css is needed). As mentioned above, the CSS files can be found within the /css/cores folder in the latest download release.
Add the data-bs-core="{default|modern|elegant}" attribute to the <html> element.

For example, here's the starter template running the modern core theme:

HTML

<!doctype html>
<html lang="en" data-bs-core="modern">
  <head>
    <!-- Required meta tags -->
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">

    <title>Starter template - Halfmoon</title>

    <!-- Halfmoon CSS -->
    <link href="https://cdn.jsdelivr.net/npm/halfmoon@2.0.2/css/halfmoon.min.css" rel="stylesheet" integrity="sha256-RjeFzczeuZHCyS+Gvz+kleETzBF/o84ZRHukze/yv6o=" crossorigin="anonymous">

    <!-- Halfmoon modern core theme -->
    <link href="https://cdn.jsdelivr.net/npm/halfmoon@2.0.2/css/cores/halfmoon.modern.css" rel="stylesheet" integrity="sha256-DD6elX+jPmbFYPsGvzodUv2+9FHkxHlVtQi0/RJVULs=" crossorigin="anonymous">

    <!-- Or just include all the core themes together:
    <link href="https://cdn.jsdelivr.net/npm/halfmoon@2.0.2/css/cores/halfmoon.cores.css" rel="stylesheet" integrity="sha256-MAzAVJMU/ze52ZHcA8CeqRrCOVndMZlHwNeS2c73vP4=" crossorigin="anonymous">
    -->
  </head>
  <body>
    <h1>Hello, world!</h1>

    <!-- Option 1: Bootstrap JS bundle with Popper -->
    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/js/bootstrap.bundle.min.js" integrity="sha256-CDOy6cOibCWEdsRiZuaHf8dSGGJRYuBGC+mjoJimHGw=" crossorigin="anonymous"></script>

    <!-- Option 2: Separate Popper and Bootstrap JS
    <script src="https://cdn.jsdelivr.net/npm/@popperjs/core@2.11.8/dist/umd/popper.min.js" integrity="sha256-whL0tQWoY1Ku1iskqPFvmZ+CHsvmRWx/PIoEvIeWh4I=" crossorigin="anonymous"></script>
    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/js/bootstrap.min.js" integrity="sha256-3gQJhtmj7YnV1fmtbVcnAV6eI4ws0Tr48bVZCThtCGQ=" crossorigin="anonymous"></script>
    -->
  </body>
</html>

Up next

Browsers and devices

Help us grow

Our main goal is to make Halfmoon the go-to framework for building websites, dashboards and tools. If you believe in our mission, consider becoming a sponsor and help us grow.

You can email us directly if you have any queries. We are always happy to answer.