2.1. Repository layout

• src/scss/: Sass sources (clearmin.scss is the entry point, _variables.scss holds every setting)
• src/js/clearmin.js: JavaScript source
• dist/: ready to use files (compiled css/js, Bootstrap, Popper & Font Awesome bundles, fonts, images)
• demo/ and docs/: demo pages and this documentation

2.2. CSS and JS files

CSS files (<head>):

• dist/css/clearmin.min.css (Bootstrap 5.3 + Clearmin theme)
• dist/css/roboto.css (main font)
• dist/css/small-n-flat.css (small-n-flat colored svg icons classes)
• dist/fontawesome/css/all.min.css (Font Awesome 7 Free icons)

JavaScript files (just before </body>):

• dist/js/popper.min.js (required by Bootstrap dropdowns, tooltips and popovers)
• dist/js/bootstrap.min.js (Bootstrap widgets)
• dist/js/clearmin.min.js (Clearmin layout)

---

2.3. Body classes

• cm-no-transition: must be present to prevent browsers from starting transitions on page load
• cm-1-navbar: when one navbar is present on your page
• cm-2-navbar: when two navbars are present on your page
• cm-3-navbar: when three navbars are present on your page
• cm-menu-toggled: if you want the menu to be toggled on page load (see next section)

---

2.4. Preserving left menu state between pages

When the user chooses the condensed version of the side menu, we want it to stay in this state on the next page. To achieve this, a cookie is automatically set to reflect the menu state.

There are two different ways to restore this state:

• Server-side (recommended): when your server receives a cookie named "cm-menu-toggled" with value "true", just add the .cm-menu-toggled class to the body tag.
• Client-side: nothing to do, .cm-menu-toggled is automatically added to the body when needed, but it can cause a blinking reflow on some browsers.

---

2.5. Content containers

• Don't forget the <div id="global"> to contain the page (e.g. minimal template)
• Use one or many <div class="container-fluid"> to contain your content
• Add .cm-fix-height to a .row to give the same height to all its cards

Here is the minimal code to build a Clearmin navbar (navbars must be placed inside <header id="cm-header">):

<nav class="cm-navbar cm-navbar-default">
  <div class="cm-flex"></div>
</nav>

• .cm-flex takes all the available space, other direct children are square shaped (unless a width is specified)
• You can replace .cm-navbar-default by any theme color: primary, success, info, warning, danger, gray, yellow, purple, turquoise, midnight... (e.g. .cm-navbar-turquoise)

You can add as many buttons as you want, before and after .cm-flex: they are displayed in source order.
Several types of widgets can be inserted in a navbar:

• Breadcrumbs
• Tabs (default navbar only)
• Search bar
• Popovers (a .dropdown-menu.cm-popover opened by a Bootstrap dropdown toggle)
• Dropdowns (use .dropdown-menu-end for right side buttons)

Check this demo page and pick what you need!

4.1. Structure

Here is a basic example:

<div id="cm-menu">
  <nav class="cm-navbar cm-navbar-primary">
    <div class="cm-flex"><div class="cm-logo"></div></div>
    <button type="button" class="btn btn-primary" data-toggle="cm-menu" aria-label="Toggle menu"><i class="fa-solid fa-bars" aria-hidden="true"></i></button>
  </nav>
  <div id="cm-menu-content">
    <div id="cm-menu-items-wrapper">
      <div id="cm-menu-scroller">
        <ul class="cm-menu-items">
          <li><a href="index.html" class="sf-house">Home</a></li>
        </ul>
      </div>
    </div>
  </div>
</div>

If you want to add some custom html content in that menu, you should include it into the <ul class="cm-menu-items"> to prevent scroll bugs when the menu content exceeds the page height.

---

4.2. Logo

Set the $cm-logo Sass variable (see Sass & build), or override the rule in your own stylesheet:

#cm-menu .cm-logo {
  background: url(../img/your-logo-here.svg) no-repeat 15px center;
}

---

4.3. Submenu items

Only one level of submenu is supported, here is the code to add one:

<li class="cm-submenu">
  <a class="an-icon-class">My Submenu <span class="caret"></span></a>
  <ul>
    <li><a href="link1.html">Link 1</a></li>
    <li><a href="link2.html">Link 2</a></li>
    <li><a href="link3.html">Link 3</a></li>
  </ul>
</li>

Clearmin ships two icon sets:

• Font Awesome 7 Free for monochrome icons (buttons, navbars, text): <i class="fa-solid fa-gear"></i>. They take the color of the text, so they are white in colored buttons.
• Small-n-flat colored 24x24px svg icons, used as background images through the classes of dist/css/small-n-flat.css (e.g. <a class="sf-house"> in the left menu). To lighten this file, you may delete the classes you don't use.

Left menu links accept either a small-n-flat class or a Font Awesome icon as first child: <a href="#"><i class="fa-solid fa-house"></i>Home</a>.

Clearmin is compiled from the Bootstrap 5.3 Sass sources. Install the dependencies once, then build:

npm install
npm run build   # dist/css/clearmin(.min).css, dist/js/clearmin(.min).js + Bootstrap & Popper bundles
npm run watch   # recompile dist/css/clearmin.css on change

Every variable of src/scss/_variables.scss is !default: Clearmin specific ones, and the Bootstrap ones it overrides (colors, fonts, spacing...). Here are the Clearmin ones:

$cm-translen-global:   150ms;  // Transition duration for layout based animations
$cm-translen-widget:   150ms;  // Transition duration for modals, popovers, dropdowns...
$cm-translen-button:   75ms;   // Transition duration for .btn items
$cm-menu-width:        262px;  // Left menu width
$cm-navbar-height:     50px;   // Navbars height (and condensed menu width)
$cm-border-global:     #ccc;   // Default border color for several items
$cm-underliner-height: 3px;    // Height of underline in left menu and nav tabs
$cm-body-bg:           #eee;   // Page background
$cm-logo:              url("../img/logo.svg");
$cm-desktop-breakpoint: lg;    // Breakpoint from which the menu is docked
$cm-title-font-size:   $font-size-base;          // Navbar titles, breadcrumbs, search
$cm-caps-font-size:    $font-size-base * .9286;  // Uppercase card headers & navbar tabs
$cm-icon-font-size:    $font-size-base * 1.2857; // Icons in navbar buttons and menu
$cm-theme-colors: ("gray": ..., "yellow": ..., "purple": ..., "turquoise": ..., "midnight": ...);

The base font size is 16px ($font-size-base: 1rem). Every text related size (headings, buttons, inputs, tables, dropdowns, the variables above...) is a ratio of it, so changing $font-size-base rescales the whole typography proportionally while the layout (navbar height, menu width, gutters) stays the same.

To customize Clearmin without touching its sources, create your own entry file and compile it with node_modules in the Sass load path (sass --load-path=node_modules my-theme.scss):

// my-theme.scss
$primary: #8e44ad;
$cm-menu-width: 240px;

@import "clearmin/src/scss/clearmin";

clearmin.js initializes itself when the DOM is ready. To change the defaults, define window.CMConfig before loading it:

<script>
  window.CMConfig = {
    navbarHeight: 50,       // should reflect the $cm-navbar-height Sass variable
    menuSwiper: true,       // enable swipe gesture (toggle menu) on touch devices
    menuSwiperIOS: true,    // enable swipe gesture on iOS Safari
    restoreMenuState: true  // client-side menu state restoration
  }
</script>
<script src="dist/js/clearmin.min.js"></script>

Clearmin also initializes every Bootstrap tooltip ([data-bs-toggle="tooltip"]) and popover ([data-bs-toggle="popover"]) of the page. The instance is available as window.CM (e.g. CM.menu.toggle()).

8.1. Dark mode

Clearmin supports Bootstrap 5.3 color modes. Add a toggle button anywhere (its <i> icon switches between moon and sun):

<button type="button" class="btn btn-primary" data-toggle="cm-theme" aria-label="Toggle dark mode"><i class="fa-solid fa-moon"></i></button>

The choice is stored in localStorage (cm-theme); without a choice, the OS preference is followed. To avoid a flash of the wrong mode on page load, add this line in <head>:

<script>try{document.documentElement.dataset.bsTheme=localStorage.getItem('cm-theme')||(matchMedia('(prefers-color-scheme: dark)').matches?'dark':'light')}catch(e){}</script>

From JavaScript: CM.theme.set('dark'), CM.theme.get(), and listen to the cm:themechange event on document to update charts & co. Clearmin surfaces are CSS variables (--cm-surface, --cm-body-bg, --cm-border, --cm-muted...) whose dark values are set with the $cm-*-dark Sass variables.

The dark mode has its own "midnight jewel" palette: ink blue surfaces, and deeper jewel tones replacing the flat colors ($cm-theme-colors-dark: sapphire primary, emerald success, copper warning, garnet danger, jade turquoise, amethyst purple...). Each tone has a luminous companion for text on dark surfaces ($cm-theme-colors-dark-emphasis: mint, aqua, apricot, coral...), used by alerts, .text-* / .link-* utilities and form validation; contextual table rows get jewel tinted dark backgrounds. Buttons, navbars, badges, alerts and the --bs-* color variables all switch to it, so charts can read them too (see how the Chart.js charts of the demo dashboards follow the color mode). Set $cm-glow-dark: false to disable the aurora background and glowing accents. In dark mode, the default .cm-navbar-primary header and menu navbars become midnight ($cm-navbar-dark-color, null to keep primary); navbars using another color keep it.

---

8.2. Stat cards

KPI tiles for the top of dashboards (see the sales dashboard):

<div class="card cm-stat">
  <div class="card-body">
    <div class="cm-stat-icon bg-primary-subtle text-primary-emphasis"><i class="fa-solid fa-cart-shopping"></i></div>
    <div class="cm-stat-label">Orders</div>
    <div class="cm-stat-value">1,284</div>
    <div class="cm-stat-trend text-success"><i class="fa-solid fa-arrow-trend-up"></i> 8.1% <span>vs last month</span></div>
    <div class="cm-stat-sparkline"><canvas></canvas></div> <!-- optional -->
  </div>
</div>

---

The optional .cm-stat-sparkline is an edge to edge area at the bottom of the card for a small chart. Charts need a sized, positioned container: .cm-chart (e.g. <div class="cm-chart" style="height:320px"><canvas></canvas></div>). The demo dashboards (sales, website visitors, server stats) use Chart.js (MIT): demo/assets/js/charts.js holds reusable helpers (theme colors, gauges, sparklines, doughnuts, redraw on cm:themechange) and demo/assets/js/dashboard-*.js the charts of each page, including live updating ones. A <span class="badge text-bg-danger cm-live">Live</span> badge shows a pulsing dot.

---

8.3. Data tables

Sortable, filterable and paginated tables without any plugin (see the data tables demo):

<input type="search" class="form-control" data-cm-table-filter="#customers">
<table id="customers" class="table" data-cm-table data-cm-page-size="10">
  <thead>
    <tr>
      <th data-sort>Name</th>
      <th data-sort="number">MRR</th>
      <th data-sort="date">Customer since</th>
    </tr>
  </thead>
  <tbody>
    <tr><td>Emma Martin</td><td data-value="490">$490</td><td data-value="2024-03-12">Mar 12, 2024</td></tr>
  </tbody>
</table>

• data-sort makes a column sortable (text by default, number or date); a cell can give its sort value in data-value
• data-cm-page-size enables pagination; an info line and the pagination are added after the table
• any input with data-cm-table-filter="#table-id" filters the rows

---

8.4. Toasts

Show a notification in the bottom right corner, declaratively or from JavaScript:

<button class="btn btn-primary" data-cm-toast="Your changes have been saved." data-cm-toast-title="Saved" data-cm-toast-color="success">Save</button>

CM.toast('Your changes have been saved.', { title: 'Saved', color: 'success', delay: 4000 })

Follow the official Bootstrap migration guide for the Bootstrap components, then for Clearmin itself:

• Drop jQuery, jquery.cookie, jquery.mousewheel and fastclick; load popper.min.js before bootstrap.min.js
• bootstrap-clearmin.min.css is now clearmin.min.css
• .panel becomes .card (.card-header, .card-body)
• In navbars, .pull-right is no longer needed; dropdowns use data-bs-toggle="dropdown"
• Navbar popovers: .popover.cm-popover.bottom + .arrow become .dropdown-menu.cm-popover + .cm-popover-arrow
• Navbar tabs and breadcrumbs use the Bootstrap 5 markup (.nav-item / .nav-link, .breadcrumb-item)
• .btn-light (faded button) is renamed .btn-faded, .btn-light being a Bootstrap 5 color
• .text-overflow is replaced by Bootstrap's .text-truncate
• .hidden-md.hidden-lg on the header menu button becomes .d-lg-none
• Material design icons (.md-*) are removed: use Font Awesome 7 icons inside buttons (<i class="fa-solid fa-bars"></i>); Font Awesome 4 class names must be updated (fa fa-cog → fa-solid fa-gear...)