Gentelella

https://gentelella.colorlib.com/docs/
Admin
Gentelella is a free, MIT-licensed HTML admin dashboard template, with v4 being a ground-up rewrite...
Tokens:50,820
Snippets:557
Trust Score:10
Update:3 months ago
Show doc for...
Tokens:
Raw
### Installing and Importing a Gentelella Fork

Source: https://gentelella.colorlib.com/docs/deployment

How to install your fork via NPM and import its components and SCSS. Ensure the package name matches your fork's name.

```javascript
npm install your-gentelella-fork
```

```javascript
import { mountShell, showModal } from 'your-gentelella-fork';
import 'your-gentelella-fork/scss/v4/main.scss';
```

--------------------------------

### Install Gentelella via Git Clone

Source: https://gentelella.colorlib.com/docs

Clone the Gentelella repository and install its dependencies to set up the project locally. This method is suitable for starting from the template.

```bash
git clone https://github.com/ColorlibHQ/gentelella.git
cd gentelella
npm install
```

--------------------------------

### Run the Development Server

Source: https://gentelella.colorlib.com/docs

Start the development server using npm. This command boots Vite with hot module replacement for live updates on SCSS, JS, and HTML changes in the src/ directory.

```bash
npm run dev
```

--------------------------------

### Build and Preview PWA Locally

Source: https://gentelella.colorlib.com/docs/pwa

Run these commands to build the project and preview it locally. Use this environment to verify PWA installation criteria and service worker behavior in Chrome DevTools.

```bash
npm run build
npm run preview
```

--------------------------------

### Side-by-Side Deployment Structure

Source: https://gentelella.colorlib.com/docs/migration-v2

Illustrates a directory structure for running both v2 and v4 builds concurrently during a migration. This setup facilitates A/B testing and phased cutovers.

```bash
deploys/
├── v2/                    # current production
└── v4-beta/               # new build
```

--------------------------------

### Checkbox and Radio Button Examples

Source: https://gentelella.colorlib.com/docs/forms

Basic implementation for checkboxes and radio buttons using the '.form-check' class for proper styling.

```html
<label class="form-check">
  <input type="checkbox" name="terms">
  <span>I agree to the terms</span>
</label>

<label class="form-check">
  <input type="radio" name="plan" value="pro">
  <span>Pro plan</span>
</label>
```

--------------------------------

### Input with Prefix and Suffix Example

Source: https://gentelella.colorlib.com/docs/forms

Use the '.input-affix' class to add static text or icons before or after an input field. The leading affix should have the '.prefix' class.

```html
<div class="form-group">
  <label class="form-label" for="price">Price</label>
  <div class="input-affix">
    <span class="affix prefix">$</span>
    <input type="number" id="price" class="form-control" placeholder="0.00">
    <span class="affix">.00</span>
  </div>
</div>
```

--------------------------------

### Install Gentelella npm Package

Source: https://gentelella.colorlib.com/docs/typescript

Command to install the Gentelella library as an npm dependency in your project.

```bash
npm install gentelella
```

--------------------------------

### Import and Use Gentelella v4 Components

Source: https://gentelella.colorlib.com/docs/typescript

Example of importing core Gentelella v4 components and SCSS into a TypeScript project and initializing the shell.

```typescript
import { mountShell, showModal, showToast } from 'gentelella';
import 'gentelella/scss/v4/main.scss';
import type { Action } from 'gentelella/v4/modal';

mountShell();

const actions: Action[] = [
  { label: 'OK', variant: 'primary', action: () => {} }
];

showModal({ title: 'Hello', actions });
```

--------------------------------

### Install Gentelella via npm Package

Source: https://gentelella.colorlib.com/docs

Install Gentelella as a package into your existing project to use its helpers and styles. This is for integrating Gentelella's components into your application.

```bash
npm install gentelella
```

```javascript
import { mountShell, showModal, showToast } from 'gentelella';
import 'gentelella/scss/v4/main.scss';
```

--------------------------------

### Select Input Example

Source: https://gentelella.colorlib.com/docs/forms

Standard HTML select element for dropdowns. For multi-select functionality, a custom control is available.

```html
<div class="form-group">
  <label class="form-label" for="country">Country</label>
  <select id="country" class="form-control">
    <option>United States</option>
    <option>Latvia</option>
    <option>Japan</option>
  </select>
</div>
```

--------------------------------

### Implement Optimistic UI Update

Source: https://gentelella.colorlib.com/docs/data-adapter

Implement an optimistic UI update pattern for actions like moving an item between columns. This example shows how to update the UI immediately and revert on failure.

```javascript
// optimistic
async function move(id, column) {
  const card = cards.find(c => c.id === id);
  card.column = column;
  render();

  try {
    await adapter.update(id, { column });
  } catch (e) {
    card.column = previousColumn;
    render();
    showToast('Move failed', { variant: 'error' });
  }
}
```

--------------------------------

### Inbox Data Adapter Setup

Source: https://gentelella.colorlib.com/docs/data-adapter

Sets up the data adapter for the inbox, choosing between an HTTP adapter for API calls or a seed adapter for local data. Requires `useApiMode`, `seedAdapter`, and `httpAdapter` imports.

```javascript
import { useApiMode, seedAdapter, httpAdapter } from './data-adapter.js';

const SEED = [/* ... */];

const adapter = useApiMode()
  ? httpAdapter('/api/messages') 
  : seedAdapter(SEED, filterByFolder);

async function loadFolder(folder) {
  const messages = await adapter.list({ folder });
  renderList(messages);
}

async function markRead(id) {
  await adapter.update(id, { unread: false });
  // optimistically update DOM
}
```

--------------------------------

### Adding Type Definitions for New Modules

Source: https://gentelella.colorlib.com/docs/typescript

Example of how to declare types for a new JavaScript module in a TypeScript project using a declaration file.

```typescript
declare module 'gentelella/v4/reports' {
  export interface ReportConfig {
    range: 'day' | 'week' | 'month';
    metric: string;
  }

  export function initReports(): void;
  export function buildReport(config: ReportConfig): Promise<Blob>;
}
```

--------------------------------

### Conditional API Mode Based on Hostname

Source: https://gentelella.colorlib.com/docs/data-adapter

Provides an example of setting the `window.__GENTELELLA_API__` flag conditionally, enabling API mode for all hostnames except 'localhost'.

```html
<script>
  if (location.hostname !== 'localhost') {
    window.__GENTELELLA_API__ = true;
  }
</script>
```

--------------------------------

### HTTP Error Handling with httpAdapter

Source: https://gentelella.colorlib.com/docs/data-adapter

The `httpAdapter` throws `HttpError` for non-2xx responses. This example shows how to catch and handle specific HTTP error statuses.

```javascript
import { HttpError } from './v4/data-adapter.js';

try {
  await adapter.update(id, patch);
} catch (e) {
  if (e instanceof HttpError && e.status === 404) {
    showToast('Item not found', { variant: 'error' });
  } else if (e instanceof HttpError && e.status >= 500) {
    showToast('Server error — try again', { variant: 'error' });
  } else {
    throw e;
  }
}
```

--------------------------------

### Get Data Adapter for Custom Page

Source: https://gentelella.colorlib.com/docs/data-adapter

Initializes the data adapter for a custom page. It conditionally uses `httpAdapter` if `useApiMode` is true, otherwise it uses `seedAdapter` with the defined `SEED`.

```javascript
const adapter = useApiMode() ? httpAdapter('/api/customers') : seedAdapter(SEED);
```

--------------------------------

### Bind Custom Shortcut to Open Command Palette

Source: https://gentelella.colorlib.com/docs/palette

Listen for a keydown event and open the command palette programmatically. This example binds Ctrl+P or Cmd+P to trigger the palette.

```javascript
import { openCommandPalette, closeCommandPalette } from '/src/v4/command-palette.js';

// Bind to a different shortcut
document.addEventListener('keydown', (e) => {
  if (e.key === 'p' && (e.metaKey || e.ctrlKey)) {
    e.preventDefault();
    openCommandPalette();
  }
});
```

--------------------------------

### Standard Form Input Example

Source: https://gentelella.colorlib.com/docs/forms

Use this for standard text-based inputs like email. Ensure the 'required' attribute is used for mandatory fields. The '.form-help' class provides subtle guidance below the input.

```html
<div class="form-group">
  <label class="form-label" for="email">Email <span class="required">*</span></label>
  <input type="email" id="email" class="form-control" name="email" placeholder="you@example.com" required>
  <div class="form-help">We'll never share your email.</div>
</div>
```

--------------------------------

### Import Individual ES-Module Helpers via CDN

Source: https://gentelella.colorlib.com/docs

Import individual ES-module helpers like modal and toast directly from the CDN. Ensure the paths under src/v4/ are stable. This method is useful for leveraging specific functionalities without a full installation.

```html
<script type="module">
  import { showModal } from 'https://cdn.jsdelivr.net/npm/gentelella@4/src/v4/modal.js';
  import { showToast } from 'https://cdn.jsdelivr.net/npm/gentelella@4/src/v4/toast.js';
  showToast('Hello from CDN', { variant: 'success' });
</script>
```

--------------------------------

### GitHub Actions Workflow for GitHub Pages Deployment

Source: https://gentelella.colorlib.com/docs/deployment

A GitHub Actions workflow to deploy a static site to GitHub Pages. It checks out the code, sets up Node.js, installs dependencies, builds the project with a base path, uploads the build artifact, and deploys to GitHub Pages.

```yaml
# .github/workflows/deploy.yml
name: Deploy
on:
  push:
    branches: [master]

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20', cache: 'npm' }
      - run: npm ci
      - run: BASE_PATH=/${{ github.event.repository.name }}/ npm run build
      - uses: actions/upload-pages-artifact@v3
        with: { path: dist }
      - uses: actions/deploy-pages@v4
```

--------------------------------

### Pre-deploy Checklist

Source: https://gentelella.colorlib.com/docs/deployment

Run these commands to ensure code quality, build the project, and perform a basic sanity check on the output directory before deployment. Verify file sizes and contents.

```bash
npm run lint
```

```bash
npm run build
```

```bash
ls -la dist/
```

```bash
du -sh dist/
```

--------------------------------

### Run Production Builds

Source: https://gentelella.colorlib.com/docs

Use these commands to create production-ready, minified, and hashed assets. For debugging, use the non-minified build. Preview the production build locally.

```bash
# Production — minified, hashed assets, what you'd deploy
npm run build

# Non-minified build, useful for debugging
npm run build:dev

# Preview the production build locally (serves dist/ on port 9174)
npm run preview
```

--------------------------------

### Textarea Input Example

Source: https://gentelella.colorlib.com/docs/forms

Suitable for multi-line text input. Control the height by setting the 'rows' attribute.

```html
<div class="form-group">
  <label class="form-label" for="notes">Notes</label>
  <textarea id="notes" class="form-control" rows="4"></textarea>
</div>
```

--------------------------------

### Preview Production Build

Source: https://gentelella.colorlib.com/docs/faq

After building for production, use `npm run preview` to serve the static files from the `dist/` directory. This is useful for testing the production build locally.

```bash
npm run build && npm run preview
```

--------------------------------

### Initialize Command Palette

Source: https://gentelella.colorlib.com/docs/palette

Sets up the global keybinding (Ctrl/Cmd+K) to open/close the command palette and repurposes the topbar search box as an opener. Ensures idempotency with a `_wired` flag.

```javascript
export function initCommandPalette() {
  if (initCommandPalette._wired) return;
  initCommandPalette._wired = true;

  document.addEventListener('keydown', (e) => {
    const isK = e.key === 'k' || e.key === 'K';
    if (isK && (e.metaKey || e.ctrlKey)) {
      e.preventDefault();
      host ? close() : open();
    }
  });

  // Repurpose the topbar search box
  const search = document.querySelector('.search-box input');
  if (search) {
    const opener = (e) => { e.preventDefault(); search.blur(); open(); };
    search.addEventListener('focus', opener);
    search.addEventListener('click', opener);
    search.setAttribute('readonly', '');
    search.setAttribute('aria-label', 'Open command palette');
  }
}
```

--------------------------------

### Build for Production

Source: https://gentelella.colorlib.com/docs/faq

Run the `npm run build` command to create a production-ready build of the project. The output will be placed in the `dist/` directory.

```bash
npm run build
```

--------------------------------

### Module Augmentation for Shell Module

Source: https://gentelella.colorlib.com/docs/typescript

Example of using module augmentation to add types for the `v4/shell` module, specifically for the `mountShell` function.

```typescript
declare module 'gentelella/v4/shell' {
  /** Mount the admin shell. Reads body data attributes. */
  export function mountShell(): void;
}
```

--------------------------------

### Show Modal with Type Hints

Source: https://gentelella.colorlib.com/docs/typescript

Demonstrates how to import and use the `showModal` function from a local file, with inline type hints for parameters.

```typescript
import { showModal } from './v4/modal.js';

showModal({
  title: 'Hello',
  //  ┃
  //  ┗━ string | undefined
  body: '...',
  //     ┃
  //     ┗━ string | HTMLElement | undefined
  actions: [
    //   ┃
    //   ┗━ Action[]
    { label: 'OK', variant: 'primary', action: () => true }
    //                       ┃
    //                       ┗━ "primary" | "outline" | "ghost" | "danger" | undefined
  ]
});
```

--------------------------------

### Get Selected Row Count

Source: https://gentelella.colorlib.com/docs/tables

Read the number of selected rows by querying for `tr.selected` elements within the table's tbody.

```javascript
const selected = table.querySelectorAll('tbody tr.selected').length;
```

--------------------------------

### Build Gentelella for Production

Source: https://gentelella.colorlib.com/docs/deployment

Run these commands to create production-ready static files. Use `npm run build` for a minified, hashed build suitable for deployment. `npm run build:dev` creates a non-minified version for debugging. For subpath deployments, prefix the build command with `BASE_PATH=/your/subpath/`.

```bash
# Minified, hashed, sourcemap-hidden — what you'd deploy
npm run build

# Non-minified — useful for debugging the production output
npm run build:dev

# Build at a subpath (e.g. https://example.com/admin/)
BASE_PATH=/admin/ npm run build
```

--------------------------------

### Implement Kanban Drag-and-Drop

Source: https://gentelella.colorlib.com/docs/kanban

Sets up event listeners for dragstart, dragend, dragover, and drop events on the board container for drag-and-drop functionality. Uses event delegation for efficiency.

```javascript
let draggedId = null;

function setupDnD(boardEl) {
  // ─── 1. Start drag ────────────────────────
  boardEl.addEventListener('dragstart', (e) => {
    const card = e.target.closest('.kanban-card');
    if (!card) return;
    draggedId = parseInt(card.dataset.id, 10);
    card.classList.add('dragging');

    // Firefox needs data set on dataTransfer to actually drag.
    e.dataTransfer.setData('text/plain', String(draggedId));
  });

  // ─── 2. End drag (cleanup) ────────────────
  boardEl.addEventListener('dragend', (e) => {
    const card = e.target.closest('.kanban-card');
    if (card) card.classList.remove('dragging');
    document.querySelectorAll('.kanban-column-body.drop-target')
      .forEach((el) => el.classList.remove('drop-target'));
    draggedId = null;
  });

  // ─── 3. Allow drop on column bodies ────────
  boardEl.addEventListener('dragover', (e) => {
    const col = e.target.closest('.kanban-column-body');
    if (col) {
      e.preventDefault();                       // Required to allow drop
      col.classList.add('drop-target');
    }
  });

  // ─── 4. Drop ───────────────────────────────
  boardEl.addEventListener('drop', (e) => {
    const col = e.target.closest('.kanban-column-body');
    if (!col || draggedId === null) return;
    e.preventDefault();

    const newColumn = col.dataset.drop;
    const card = cards.find((c) => c.id === draggedId);
    if (!card) return;

    card.col = newColumn;
    render();                                   // Repaint everything
    showToast(`Moved to ${columnTitle(newColumn)}`, { variant: 'success' });
  });
}
```

--------------------------------

### Write ECharts Factory Function

Source: https://gentelella.colorlib.com/docs/echarts

Define a factory function for a new chart type. This example creates a 'quick-spark' line chart with predefined data and styling.

```javascript
function quickSpark(echarts, el, t) {
  const chart = echarts.init(el);
  chart.setOption({
    ...baseOption(t),
    grid: { left: 0, right: 0, top: 4, bottom: 0 },
    xAxis: { show: false, type: 'category' },
    yAxis: { show: false, type: 'value' },
    series: [{
      type: 'line',
      data: [12, 14, 18, 22, 28, 32, 40],
      smooth: true,
      lineStyle: { color: t.primary, width: 2 },
      itemStyle: { color: t.primary },
      symbol: 'none',
      areaStyle: { color: hexToRgba(t.primary, 0.15) }
    }]
  });
  return chart;
}
```

--------------------------------

### Production Build Commands

Source: https://gentelella.colorlib.com/docs/getting-started

Commands to create minified, hashed assets for deployment, non-minified builds for debugging, and previewing the production build locally.

```bash
npm run build

# Non-minified build, useful for debugging
npm run build:dev

# Preview the production build locally (serves dist/ on port 9174)
npm run preview
```

--------------------------------

### Using statTile Helper for Dynamic Content

Source: https://gentelella.colorlib.com/docs/playground

Demonstrates how to use the `statTile` helper to dynamically generate KPI cards for displaying revenue and new customer statistics. Ensure the `markup.js` module is imported.

```javascript
import {
  pageHeader, statTile, statusBadge,
  customerCell, activityItem, visitorRow,
  emptyState, banner, skeletonRows, escapeHtml
} from '/src/v4/markup.js';

document.querySelector('[data-preview-stats]').innerHTML = `
  ${statTile({ label: 'Revenue', value: '$48,205', color: 'teal', change: '+12%' })}
  ${statTile({ label: 'New customers', value: '1,284', color: 'green', change: '+8%' })}
`;
```

--------------------------------

### Get CSS Theme Tokens

Source: https://gentelella.colorlib.com/docs/echarts

Retrieves CSS custom properties (tokens) from the document's root element. Add new tokens here if they are introduced in `_tokens.scss`.

```javascript
const tokens = () => {
  const cs = getComputedStyle(document.documentElement);
  return {
    primary:     cs.getPropertyValue('--primary').trim(),
    primaryDk:   cs.getPropertyValue('--primary-dk').trim(),
    azure:       cs.getPropertyValue('--azure').trim(),
    blue:        cs.getPropertyValue('--blue').trim(),
    yellow:      cs.getPropertyValue('--yellow').trim(),
    green:       cs.getPropertyValue('--green').trim(),
    red:         cs.getPropertyValue('--red').trim(),
    purple:      cs.getPropertyValue('--purple').trim(),
    text:        cs.getPropertyValue('--text').trim(),
    textMuted:   cs.getPropertyValue('--text-muted').trim(),
    borderLight: cs.getPropertyValue('--border-color-light').trim(),
    bgSurface:   cs.getPropertyValue('--bg-surface').trim()
  };
};
```

```javascript
return {
  // ...existing tokens...
  accentCoral: cs.getPropertyValue('--accent-coral').trim()
};
```

--------------------------------

### Data Adapter Methods

Source: https://gentelella.colorlib.com/docs/data-adapter

Demonstrates the common methods available on both HTTP and seed data adapters for managing data items.

```javascript
// Both have the same methods:
const items = await adapter.list({ folder: 'inbox' });
const item  = await adapter.get(id);
const created = await adapter.create({ subject: 'Hi' });
const updated = await adapter.update(id, { unread: false });
const removed = await adapter.remove(id);
```

--------------------------------

### Chart Initialization and Factory

Source: https://gentelella.colorlib.com/docs/typescript

Initializes charts and provides a factory map for chart configurations.

```APIDOC
## Chart Initialization

### Description
Initializes charts on the page and provides a factory map for configuring different chart types.

### Functions

#### initCharts

*   **Description**: Initializes all charts on the page.
*   **Signature**: `initCharts(): void`
*   **Module**: `gentelella/v4/charts`

### Constants

#### charts

*   **Description**: A factory map for chart configurations.
*   **Type**: `object`
*   **Module**: `gentelella/v4/charts`
```

--------------------------------

### Service Worker Implementation

Source: https://gentelella.colorlib.com/docs/pwa

Defines caching strategies for HTML (network-first) and hashed assets (cache-first). It precaches an offline page and handles installation, activation, and fetch events.

```javascript
const CACHE = 'gentelella-v4-r2';
const SCOPE = self.registration?.scope || self.location.origin + '/';
const OFFLINE_URL = new URL('production/offline.html', SCOPE).href;
const PRECACHE = [OFFLINE_URL];

self.addEventListener('install', (event) => {
  event.waitUntil(
    caches.open(CACHE)
      .then((c) => c.addAll(PRECACHE).catch(() => {}))
      .then(() => self.skipWaiting())
  );
});

self.addEventListener('activate', (event) => {
  event.waitUntil(
    caches.keys()
      .then((keys) => Promise.all(keys.filter((k) => k !== CACHE).map((k) => caches.delete(k))))
      .then(() => self.clients.claim())
  );
});

self.addEventListener('fetch', (event) => {
  const req = event.request;
  if (req.method !== 'GET') return;
  const url = new URL(req.url);
  if (url.origin !== self.location.origin) return;          // skip cross-origin

  // HTML — network first, fallback to cache, then offline page
  if (req.mode === 'navigate' || req.headers.get('accept')?.includes('text/html')) {
    event.respondWith(
      fetch(req)
        .then((res) => {
          caches.open(CACHE).then((c) => c.put(req, res.clone())).catch(() => {});
          return res;
        })
        .catch(async () =>
          (await caches.match(req)) || (await caches.match(OFFLINE_URL)) || Response.error()
        )
    );
    return;
  }

  // Hashed assets — cache first
  if (/
/(js|assets|images|fonts)
//.test(url.pathname)) {
    event.respondWith(
      caches.match(req).then((hit) => hit || fetch(req).then((res) => {
        caches.open(CACHE).then((c) => c.put(req, res.clone())).catch(() => {});
        return res;
      }))
    );
  }
});
```

--------------------------------

### PWA Manifest Configuration

Source: https://gentelella.colorlib.com/docs/pwa

This JSON defines the web app manifest for Gentelella v4. Configure name, icons, theme color, and shortcuts for PWA installation and behavior.

```json
{
  "name": "Gentelella v4 — Admin Dashboard",
  "short_name": "Gentelella",
  "description": "Modern admin dashboard template — vanilla JS, real ECharts and DataTables, no Bootstrap, no jQuery.",
  "icons": [
    { "src": "images/android-chrome-192x192.svg", "sizes": "192x192", "type": "image/svg+xml", "purpose": "any" },
    { "src": "images/android-chrome-512x512.svg", "sizes": "512x512", "type": "image/svg+xml", "purpose": "any" },
    { "src": "images/android-chrome-512x512.svg", "sizes": "512x512", "type": "image/svg+xml", "purpose": "maskable" }
  ],
  "theme_color": "#1ABB9C",
  "background_color": "#f5f7fb",
  "display": "standalone",
  "orientation": "any",
  "scope": "./",
  "start_url": "production/index.html",
  "id": "gentelella-v4",
  "lang": "en",
  "categories": ["productivity", "business", "developer"],
  "shortcuts": [
    { "name": "Dashboard", "url": "production/index.html" },
    { "name": "Inbox",     "url": "production/inbox.html" },
    { "name": "Calendar",  "url": "production/calendar.html" },
    { "name": "Settings",  "url": "production/settings.html" }
  ]
}
```

--------------------------------

### Publishing a Gentelella Fork to NPM

Source: https://gentelella.colorlib.com/docs/deployment

Commands to update version, lint, and publish your fork. The `prepublishOnly` hook ensures the build is run before publishing.

```bash
# Update version in package.json
npm run lint           # must pass
npm publish            # prepublishOnly runs `npm run build` first
```

--------------------------------

### Add New Accent Token

Source: https://gentelella.colorlib.com/docs/theming

Define a new CSS variable, like `--accent-coral`, in `_tokens.scss` for custom styling. This example shows how to set it for both light and dark themes.

```scss
/* _tokens.scss */
:root {
  --accent-coral: #FF6B6B;
}

:root[data-theme="dark"] {
  --accent-coral: #FF8787;
}
```

```css
/* _components.scss (or wherever you need it) */
.my-component {
  background: var(--accent-coral);
}
```

--------------------------------

### Initialize Component Playground Script

Source: https://gentelella.colorlib.com/docs/playground

This script iterates through component cards, extracts original HTML, builds a source panel with reset and copy buttons, and enables live editing. It uses debounced input for preview updates and clipboard API for copying.

```javascript
document.querySelectorAll('[data-source]').forEach((card) => {
  const preview = card.querySelector('[data-preview]');
  if (!preview) return;

  const originalHtml = preview.innerHTML.trim();
  const label = card.dataset.sourceLabel || '';
  const code = indent(originalHtml);

  // Build the source panel (label, Reset/Copy buttons, editable <pre>)
  const block = document.createElement('div');
  block.className = 'pg-source';
  // ... see the source for the full markup
  block.querySelector('.pg-code').textContent = code;
  card.appendChild(block);

  // Live edit, debounced 250ms
  block.querySelector('.pg-code').addEventListener('input', (e) => {
    clearTimeout(editTimer);
    editTimer = setTimeout(() => {
      preview.innerHTML = e.target.textContent;
    }, 250);
  });

  // Copy to clipboard
  block.querySelector('.pg-copy').addEventListener('click', async () => {
    await navigator.clipboard.writeText(code);
    showToast('Copied to clipboard', { variant: 'success' });
  });
});
```

--------------------------------

### Table Initialization

Source: https://gentelella.colorlib.com/docs/typescript

Initializes tables on the page.

```APIDOC
## initTables

### Description
Initializes tables on the page.

### Signature
`initTables(): void`

### Module
`gentelella/v4/tables`
```

--------------------------------

### Build and Deploy to Cloudflare Pages with Wrangler

Source: https://gentelella.colorlib.com/docs/deployment

Build the project and then deploy the output directory to Cloudflare Pages using the Wrangler CLI. Ensure your project is configured with a build script and the output directory is set to 'dist'.

```bash
# Build, then deploy via Wrangler
npm run build
npx wrangler pages deploy dist --project-name=your-project
```

--------------------------------

### Netlify Configuration for Static Site Deployment

Source: https://gentelella.colorlib.com/docs/deployment

Configuration for Netlify's continuous deployment. Specifies the build command, publish directory, and Node.js version. Includes headers for service workers and aggressively cached assets.

```toml
[build]
  command = "npm run build"
  publish = "dist"

[build.environment]
  NODE_VERSION = "20"

# Service-worker scope must match the deployed path
[[headers]]
  for = "/sw.js"
  [headers.values]
    Cache-Control = "no-cache"
    Service-Worker-Allowed = "/"

# Cache hashed assets aggressively
[[headers]]
  for = "/js/*"
  [headers.values]
    Cache-Control = "public, max-age=31536000, immutable"

[[headers]]
  for = "/assets/*"
  [headers.values]
    Cache-Control = "public, max-age=31536000, immutable"

[[headers]]
  for = "/images/*"
  [headers.values]
    Cache-Control = "public, max-age=31536000, immutable"
```

--------------------------------

### Execute Other Project Scripts

Source: https://gentelella.colorlib.com/docs

A collection of utility scripts for analyzing bundles, capturing screenshots, linting, and formatting code. The screenshots script is used for generating README and documentation preview images.

```bash
npm run analyze       Build + open the bundle treemap (rollup-plugin-visualizer)
npm run screenshots   Boot Playwright + capture 44 PNGs to docs/screenshots/
npm run lint          ESLint across src/
npm run format        Prettier write across src/
```

--------------------------------

### Update Service Worker Cache Version

Source: https://gentelella.colorlib.com/docs/pwa

Bump the CACHE constant in sw.js on every release to invalidate the cache and ensure users get the latest version. The activate handler automatically removes old caches.

```javascript
const CACHE = 'gentelella-v4-r3';   // was 'gentelella-v4-r2'
```

--------------------------------

### Create New HTML Page for Reports

Source: https://gentelella.colorlib.com/docs/adding-pages

Drop this HTML file into the `production/` directory. Ensure the `data-page` attribute matches the key you will add to the `NAV` array in the next step.

```html
<!-- production/reports.html -->
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Reports | Gentelella 2026 v4</title>
  <link rel="icon" href="../images/favicon.svg" type="image/svg+xml">
  <link rel="preconnect" href="https://fonts.googleapis.com">
  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap" rel="stylesheet">
  <script type="module" src="/src/main-v4.js"></script>
</head>
<body data-shell="admin" data-page="reports" data-breadcrumb="Home > Reports">

  <main class="main">
    <div class="page-wrapper">
      <div class="page-header">
        <div class="page-header-row">
          <div>
            <div class="pretitle">Q2 2026</div>
            <h1 class="page-title">Reports</h1>
          </div>
        </div>
      </div>

      <div class="card">
        <div class="card-header">
          <h3 class="card-title">Your content here</h3>
        </div>
        <div class="card-body">
          <!-- your page content -->
        </div>
      </div>
    </div>
  </main>

</body>
</html>
```

--------------------------------

### Disable PWA Service Worker Registration

Source: https://gentelella.colorlib.com/docs/pwa

To disable the PWA's offline support while keeping it installable, remove the service worker registration block from main-v4.js. This prevents the SW from registering but allows the manifest to still function.

```javascript
if ('serviceWorker' in navigator) {
  // ... registration code to be removed
}
```

--------------------------------

### Vite Server Configuration

Source: https://gentelella.colorlib.com/docs/vite-build

Configure the development server port, proxy settings, and auto-opening behavior.

```javascript
server: {
  open: '/production/index.html',
  port: Number(process.env.PORT) || 9173,
  host: true,
  proxy: {
    '/api': {
      target: process.env.API_URL || 'http://localhost:8080',
      changeOrigin: true
    }
  }
}
```

--------------------------------

### Customize DataTables Language Options

Source: https://gentelella.colorlib.com/docs/tables

Translate DataTables UI strings like search prompts, pagination labels, and info messages by modifying the `language` block in `initTables`. This example shows how to set a custom placeholder and pagination symbols.

```javascript
language: {
  search: '',                                  // No "Search:" label
  searchPlaceholder: 'Search…',
  info: 'Showing _START_–_END_ of _TOTAL_',
  infoEmpty: 'No matching records',
  infoFiltered: '(of _MAX_ total)',
  zeroRecords: 'No matches found',
  paginate: { previous: '←', next: '→' }
}
```

--------------------------------

### Forcing API Mode with Script Tag

Source: https://gentelella.colorlib.com/docs/data-adapter

Demonstrates how to force API mode in production by setting a global variable `window.__GENTELELLA_API__` before loading the main module.

```html
<script>window.__GENTELELLA_API__ = true;</script>
<script type="module" src="/src/main-v4.js"></script>
```

--------------------------------

### Scaffolding Command: v2 vs v4

Source: https://gentelella.colorlib.com/docs/migration-v2

v2 required manual edits to vite.config.js for new pages. v4 uses an auto-discovery and scaffolder system with commands like `npm run new`.

```bash
# v2 — manual edits to vite.config.js after creating production/<page>.html

# v4 — auto-discovery + scaffolder
npm run new -- reports --title "Reports" --nav-group "Admin"
```

--------------------------------

### Data Adapter Initialization

Source: https://gentelella.colorlib.com/docs/data-adapter

Initializes the data adapter, choosing between an HTTP adapter for API calls or a seed adapter for in-memory data based on the API mode.

```javascript
const adapter = useApiMode()
  ? httpAdapter('/api/messages')
  : seedAdapter(SEED);
```

--------------------------------

### AWS S3 Sync for Static Assets and HTML

Source: https://gentelella.colorlib.com/docs/deployment

Syncs the build output directory to an S3 bucket with different caching strategies for hashed assets and HTML files. Hashed assets are cached aggressively, while HTML, service workers, and manifest files are not cached to ensure users get the latest versions.

```bash
npm run build

# Long-cache hashed assets
aws s3 sync dist/ s3://your-bucket/ --delete \
  --cache-control "public, max-age=31536000, immutable" \
  --exclude "*.html" --exclude "sw.js" --exclude "site.webmanifest"

# No-cache for HTML so users always get fresh references
aws s3 sync dist/ s3://your-bucket/ \
  --cache-control "public, max-age=0, must-revalidate" \
  --include "*.html" --include "sw.js" --include "site.webmanifest"
```

--------------------------------

### Vercel Configuration for Static Site Deployment

Source: https://gentelella.colorlib.com/docs/deployment

Configuration for Vercel deployment. Defines the build command, output directory, and caching headers for static assets and service workers. Set framework to null if not using a specific framework integration.

```json
{
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "framework": null,
  "headers": [
    {
      "source": "/(js|assets|images|fonts)/(.*)",
      "headers": [
        { "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }
      ]
    },
    {
      "source": "/sw.js",
      "headers": [
        { "key": "Cache-Control", "value": "no-cache" }
      ]
    }
  ]
}
```

--------------------------------

### Verify Subpath Deployment Locally

Source: https://gentelella.colorlib.com/docs/deployment

Use the same BASE_PATH environment variable when running the preview command to test the subpath deployment locally. This ensures assets are correctly prefixed and accessible.

```bash
BASE_PATH=/admin/ npm run preview
```

--------------------------------

### Gentelella Production Build Output Structure

Source: https://gentelella.colorlib.com/docs/deployment

The `dist/` directory contains all static assets for deployment. It includes minified JS and CSS with content hashes for cache busting, static HTML pages, and other assets like fonts and images. The service worker (`sw.js`) is not hashed to ensure a stable URL.

```treeview
dist/
├── production/
│   ├── index.html              # Operations dashboard
│   ├── inbox.html              # Inbox client
│   ├── kanban.html             # Drag-drop board
│   ├── theme.html              # Live theme generator
│   ├── playground.html         # Component playground
│   ├── offline.html            # SW fallback
│   └── ...                     # 58 pages total
├── js/
│   ├── main-[hash].js          # Entry chunk for index.html
│   ├── inbox-[hash].js         # Lazy-loaded inbox module
│   ├── kanban-[hash].js
│   ├── vendor-echarts-[hash].js
│   ├── vendor-tables-[hash].js
│   ├── vendor-maps-[hash].js
│   └── ...
├── assets/
│   └── main-[hash].css         # Compiled SCSS, one bundle
├── fonts/                      # If any are self-hosted (default uses Google Fonts CDN)
├── images/
│   └── favicon-[hash].svg      # ...and other content-hashed images
├── sw.js                       # Service worker (not hashed — needs stable URL)
├── site.webmanifest            # PWA manifest
└── stats.html                  # Bundle analyzer treemap
```

--------------------------------

### Configure Bundle Analyzer Plugin

Source: https://gentelella.colorlib.com/docs/vite-build

This configuration snippet shows how to wire up the `rollup-plugin-visualizer` to generate a treemap of your bundle composition, which is useful for identifying unexpectedly large packages.

```javascript
plugins: [
  visualizer({
    filename: 'dist/stats.html',
    open: false,
    gzipSize: true,
    brotliSize: true,
    template: 'treemap'
  })
]
```
Tokens:
Raw