Getting Started

Introduction

You can start working immediately with Codebase in a simple HTML setup.

Download Codebase (dist.zip) Codebase GitHub repostory

Download dist.zip, extract (unzip) it and you will find the dist/ folder containing production-ready stylesheets, scripts and cource maps:

dist/
 |  // CSS
 ├─ codebase.css        // Codebase ── with default light theme only.
 ├─ codebase-l-d.css    // Codebase & built-in light and dark themes.
 |  // JS
 ├─ activator.js        // Optional: use for Activator Components.
 ├─ activator.jquery.js // Optional: use if you need to support IE11.
 |  // Sourcemaps
 ├─ codebase.css.map
 ├─ codebase-l-d.css.map
 └─ activator.js.map

The Stylesheets

The default version of Codebase stylesheet codebase.css has everything with the default light theme applied throughout.

codebase-l-d.css is the same as codebase.css but with built-in light and dark themes. These are:

A dark theme media query preference override
CSS classes light an dark themes that require either .theme-light or .theme-dark applied to the <body> tag by a theme switcher Javascript.

Get to know Codebase by using codebase.css first. It may be all you need, if you don’t want both light and dark themes. If you do want light and dark themes, you will probably want to start with codebase.css when you begin your prototyping.

See below for more information on light and dark themes in Codebase.

The SCSS

The SCSS files are also available in this repository. If you have knowledge of Sass/SCSS and a preprocessor, you can override the Codebase !default SCSS variables.

See the Codebase SCSS library for more information.

The JavaScripts

Codebase comes with a tiny, dependency-free JavaScript named activator.js for powering HTML components such as dropdowns, tabs, and modals. See Codebase Activator Components.

There is also a jQuery dependant version named activator.jquery.js that you may use instead or activator.js – if you need to support old browsers such as IE11. See Codebase and Internet Explorer 11. (Requires an older version of jQuery, <= 2.x).

Using AlpineJS Instead of Activator

If you want more power, and if you are famililar with the modern declarative approach to building JS controlled HTML components, then I recommend you switch to using AlpineJS with Codebase instead of Activator.

For more information see Using AlpineJS or Activator in Codebase.

Alpine components are built differently to Activator components – it’s not simply about swapping the JS. If you want to use AlpineJS instead of Activator, then you will want the AlpineJS Components section of these docs.

Simple HTML Setup

Download and extract (unzip) the Codebase dist/ folder into your project.
Create your first HTML page – e.g. copying the starter example below.
Link to codebase.css in the HTML <head>, and either activator.js or alpine.js just inside the closing </body> tag.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Codebase</title>
  <link rel="stylesheet" href="dist/codebase.css">
  <script src="dist/activator.js" defer></script>
  <!-- Or <script src="link/to/alpine.js" defer></script> -->
</head>
<body>
  
  <h1>Hello world</h1>

</body>
</html>

Be sure to make the /path/to/your/codebase.css (and /path/to/your/activator.js) follow your project’s directory structure to link to your files.

Using the Codebase Light and Dark Themes

codebase-l-d.css contains a system of descendant combinator selector classes for switching between light and dark themes.

This means that you don’t need to change your HTML or chosen Codebase CSS classes – you can easily swap from codebase.css to codebase-l-d.css. Simply link to codebase-l-d.css in the <head> instead of codebase.css.

If you do that, you may see no change at all – if you are using device that has no theme preference in its operating system settings, or if you have set your OS preferences to “light theme”. But if you have your OS set to “dark theme”, then your web browser knows about this, and it will render your Codebase based project with a @media (prefers-color-scheme: dark) {...} powered dark theme.

You could just stay with this arrangement: letting the visitor’s OS determine whether your website renders on their device as light or dark. Alternatively, you can include a theme switcher JavaScript – to programatically insert either .theme-light or .theme-dark in your webpage’s opening <body> tag. These two <body> classes will override the default (light) or @media (prefers-color-scheme: dark) {...} dark mode.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Codebase</title>
  <link rel="stylesheet" href="dist/codebase-l-d.css">
  <script src="link/to/alpine.js" defer></script>
  <!-- Or <script src="dist/activator.js" defer></script> -->
  <script src="link/to/your/theme-switcher.js" defer></script>
</head>
<body>
  
  <h1>Hello world</h1>

</body>
</html>

Learn more about Codebase’s light and dark themes, and example theme-switcher.

Documentation