Skip to main content

# Documentation

Everything you need to customize, extend, and deploy CoolAdmin v3.

GitHub Quick start

## Quick start

CoolAdmin is a static HTML template — no build step, no toolchain. Open any `.html` file via a local server and you’re running.

    # Clone or download the template
    git clone https://github.com/your-username/cooladmin.git
    cd cooladmin

    # Serve locally (Python 3 example)
    python3 -m http.server 8000

    # Or with Node
    npx serve .

Then visit `http://localhost:8000/index.html`. CSS is shipped pre-built — no Sass watcher to run.

> Important

> Open files via a local server, not `file://`. Some browsers block JavaScript and CSS loading from the `file://` protocol for security reasons.

## File structure

    cooladmin/
    ├── *.html                    27 page templates (dashboards, tables, forms, etc.)
    ├── css/
    │   ├── theme.css             legacy CoolAdmin styles (kept for compat)
    │   ├── app.css        modern v3 design system
    │   └── font-face.css         Poppins font-face declarations
    ├── js/
    │   ├── vanilla-utils.js      jQuery shim ($, on, ready, etc.)
    │   ├── bootstrap5-init.js    Bootstrap 5 component init
    │   ├── main-vanilla.js       chart configs + UI behaviors + JS APIs
    │   └── modern-plugins.js     counters, lightbox, progress
    ├── vendor/                   third-party CSS/JS
    │   ├── bootstrap-5.3.8.bundle.min.js
    │   ├── fontawesome-7.3.1/
    │   ├── chartjs/
    │   └── fullcalendar-7.0.2/
    ├── images/                   logos, avatars, backgrounds
    └── README.md

Every page links the same canonical CSS chain in this order:

1. `css/font-face.css` — Poppins (legacy)
2. `https://rsms.me/inter/inter.css` — Inter (the modern font)
3. `vendor/fontawesome-7.3.1/css/all.min.css` — icons
4. `vendor/bootstrap-5.3.8.min.css` — Bootstrap base
5. `css/theme.css` — legacy theme
6. `css/app.css` — modern overlay (this is where almost everything lives)

## Color themes

Six accent-color presets ship out of the box. Use the floating palette button (bottom-right of any page) to try them, or set the body class directly:

    <body class="app theme-purple">

Available themes: `theme-blue` (default), `theme-purple`, `theme-teal`, `theme-rose`, `theme-amber`, `theme-graphite`.

To define your own theme, override the four accent variables on `body.app.theme-yourname`:

    body.app.theme-mycolor {
        --m-accent:        #ff5722;
        --m-accent-rgb:    255, 87, 34;
        --m-accent-hover:  #e64a19;
        --m-accent-soft:   #fff3e0;
    }

The user’s choice is persisted automatically in `localStorage` under the key `cooladmin.theme`.

## Typography

The default sans-serif is Inter served from `rsms.me`. The legacy Poppins is also bundled in `fonts/poppins` for offline use.

To swap fonts globally, change the `--m-font` token at the top of `css/app.css`:

    body.app {
        --m-font: "Your Font", system-ui, sans-serif;
    }

The type scale used across pages:

Element | Size | Weight
--- | --- | ---
Page header h1 | 22 px | 600
Card title | 14 px | 600
Body | 14 px | 400
Subtitle / muted | 13 px | 400
KPI value | 26 px | 600 (tabular)
Eyebrow / label | 11 px | 600 uppercase

## Components

Modern reusable patterns live under `.m-*` class names in `app.css`:

Class | Purpose
--- | ---
`.m-card` | White surface with header / body / footer
`.m-btn` | Modern button (with `--primary`, `--ghost`)
`.m-table` | Borderless table with hover rows
`.stat-card` | KPI tile with label, value, delta, sparkline
`.profile-card` | User card with avatar, name, role, socials
`.cover-card` | Card with image cover + body
`.pricing-card` | Pricing tier card with `--featured`
`.notice-card` | Inline alert card (info / success / warning / danger)
`.rank-list` | Numbered list with bars (top-N rankings)
`.empty-state` | "No data" placeholder with icon + title
`.skeleton` | Loading placeholder (with shimmer)

## JavaScript APIs

### Toast notifications

The toast system is auto-initialized on every page. Trigger it from anywhere:

    // Simple
    toast.success('Saved');
    toast.info('Heads up');
    toast.warning('Storage almost full');
    toast.error('Something went wrong');

    // Full options
    toast.show({
        title: 'New version',
        message: 'v3.1.0 is now live',
        type: 'success',
        duration: 6000,    // ms; 0 = no auto-dismiss
    });

### Command palette

Press `⌘``K` (or `Ctrl` `K`) anywhere to open. Programmatic control:

    window.cmdk.open();
    window.cmdk.close();

To add new commands, edit the `COMMANDS` array in `js/main-vanilla.js`:

    { section: 'Pages', title: 'My new page', sub: 'Custom workflow',
      href: 'my-page.html', icon: 'fa-bolt' }

### Theme switcher

The floating palette button auto-injects on every page. The user’s choice is persisted in `localStorage`. To force a theme programmatically, just toggle the body class:

    document.body.classList.remove('theme-blue', 'theme-purple', 'theme-teal',
                                    'theme-rose', 'theme-amber', 'theme-graphite');
    document.body.classList.add('theme-purple');

## Chart configurations

Charts use Chart.js 4.5. Shared helpers in `main-vanilla.js` keep configs DRY:

- `withCanvas(id, fn)` — safe per-canvas init (skips if canvas isn’t on the page)
- `kpiSparkline(ctx, opts)` — gradient-fill sparkline for KPI tiles
- `sparklineOptions()`, `lightTooltip`, `modernTooltip` — reusable option blocks

To add a new chart, append a `withCanvas` block:

    withCanvas('my-chart', (ctx) => {
        new Chart(ctx, {
            type: 'line',
            data: { /* ... */ },
            options: { ...sparklineOptions(), /* overrides */ },
        });
    });

## Adding a new page

Every dashboard-style page follows the same pattern: head → sidebar → topbar → `<main>` → scripts. The fastest way is to copy an existing page like `profile.html` and replace the main content.

1. Duplicate `profile.html` to `my-page.html`
2. Update the `<title>` and meta tags at the top
3. Replace everything inside the `<main id="main-content">` with your content
4. Add a sidebar entry by editing `build_sidebar()` in `tmp/coolupdate/migrate_chrome.py` and re-running it
5. Optionally add a command-palette entry in `main-vanilla.js`

## Dark mode

Dark-mode tokens are pre-wired but not enabled by default. To enable, set `data-bs-theme="dark"` on the `<html>` element:

    <html lang="en" data-bs-theme="dark">

The `:root` tokens swap to dark surfaces (`--m-bg`, `--m-surface`, `--m-text`, etc.). Note: a few legacy CoolAdmin styles still use hardcoded colors — a thorough dark pass is on the roadmap for v3.1.

## Deployment

Drop the entire folder onto any static host:

- Netlify / Vercel: drag-and-drop the folder, no build command needed
- Cloudflare Pages: connect your Git repo, build command empty, output directory `./`
- GitHub Pages: push the repo, enable Pages from the `main` branch
- S3 + CloudFront: sync to a bucket with public-read
- Plain shared hosting: FTP / rsync the folder up

The only external dependency is the Inter font from `rsms.me`. To go fully offline, download Inter and replace that `<link>` with a local stylesheet.

> Tip

> Strip unused vendor folders before deploy if you don’t need them — for example, drop `fullcalendar-7.0.2` if you don’t use the calendar page (saves ~825 KB).

Copyright © 2026 Colorlib. All rights reserved. Template by Colorlib.