Introduction

Overview #

Halfmoon is an open-source, MIT-licensed, responsive CSS framework. You can find everything on GitHub (opens in new tab). It has a lot of useful and interesting qualities to help you quickly build websites and web applications.

The framework's defining feature is that it is highly customizable, thanks to CSS variables. Building a core theme is remarkably easy, so much so that Halfmoon comes with three built-in core themes, with dark mode support for all themes and components. Check out this cool demo where you can switch between the core themes (default / modern / elegant) during runtime. Make sure to also switch between light and dark mode for each one.

Overview Customization and theming #

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.

Please see the customization and theming page to learn more. The built-in core themes can be found within the /css/cores folder in the latest download release. Information on how to implement them in your own site can be found in the core themes section of the aforementioned customization and theming page.

Drop-in Bootstrap replacement #

Another one of Halfmoon's defining feature is that it is a drop-in replacement for Bootstrap, meaning you can replace bootstrap.css with halfmoon.css on your website, and everything will work perfectly without any changes. Moreover, we implement no JavaScript on our own (relying instead on bootstrap.bundle.js), meaning that the entire Bootstrap ecosystem is immediately available for you to use with Halfmoon, including the component libraries for popular JS frameworks such as React, Vue, Angular, Svelte, etc.

Here's an example showing a simple card component. If you're familiar with Bootstrap, you should immediately notice how the markup and class names in Halfmoon are exactly the same.

Card title

Some quick example text to build on the card title and make up the bulk of the card's content.

Go somewhere

<div class="card" style="width: 18.75rem;">
  <img src="..." class="card-img-top" alt="...">
  <div class="card-body">
    <h5 class="card-title">Card title</h5>
    <p class="card-text">
      Some quick example text to build on the card title and make up the 
      bulk of the card's content.
    </p>
    <a href="#" class="btn btn-primary">Go somewhere</a>
  </div>
</div>

Drop-in Bootstrap replacement Why use over Bootstrap? #

The decision to use Halfmoon over Bootstrap (or vice versa) will ultimately come down to personal preferences, and the unique needs of that particular project. All we want to do is document the core differences to make the decision easier:

Standardized design

Halfmoon is designed from the ground up with a highly standardized look. This means that a lot of the components will look perfectly suited for dashboards, tools, e-commerce stores, etc. The design is intentionally standard and classic, inspired by the likes of Apple HID. This is going to be the most important factor for someone picking one over the other. If you like the look and feel here, feel free to use Halfmoon because everything else is the same.

Approach to customization

As mentioned above, Halfmoon employs a different method of customization. If you prefer CSS variables over Sass and other CSS build systems, it is recommended that you stick with Halfmoon. CSS variables are now widely supported, and they are (by far) the easiest way to theme and customize websites and applications.

Simplicity

This ties into the above point. Halfmoon has no build system—nothing to compile, variables work at runtime, etc. It is easy to get started and customize—pull in the CSS file, override the variables to fit your needs (or use the default theme), and start building right away.

Sidebar component

The only additional feature that Halfmoon has over Bootstrap is the dedicated sidebar component. Therefore, if your project absolutely needs a sidebar and you don't want to implement one yourself, feel free to use ours.

Quick start #

Ready to get started? Go to the download page to get yourself a copy of the latest version of Halfmoon. That page also contains a useful starter template. We look forward to seeing what you decide to build with Halfmoon!