Documentation

Everything you need to get started with genX.

Installation

Choose the installation method that works best for your project.

Option 1: CDN (Recommended)

The fastest way to get started. Add this script tag to your HTML:

<script src="https://cdn.genx.software/v1/bootloader.js" defer></script>

The defer attribute ensures the script runs after the DOM is ready.

Option 2: Self-Hosted

Download and host the files yourself for full control:

# Clone the repository
git clone https://github.com/adamzwasserman/genX.git

# Copy source files to your project
cp genX/src/*.js your-project/static/js/

Then reference the bootloader in your HTML:

<script src="/static/js/bootloader.js" defer></script>

Option 3: npm (Coming Soon)

npm install @genx/core

Quick Start

Once installed, you can immediately use genX attributes in your HTML:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>My Page</title>
  <script src="https://cdn.genx.software/v1/bootloader.js" defer></script>
</head>
<body>
  <!-- Currency formatting -->
  <p>Price: <span fx-format="currency">99.99</span></p>

  <!-- Phone number formatting -->
  <p>Call us: <span fx-format="phone">5551234567</span></p>

  <!-- Date formatting -->
  <p>Published: <span fx-format="date" fx-date-format="long">2024-03-15</span></p>
</body>
</html>

How It Works

genX uses a lightweight bootloader that:

Scans your page for genX attributes when the DOM is ready
Detects which modules are needed based on attribute prefixes
Loads only the required modules on-demand
Processes elements with the appropriate module
Watches for dynamic content via MutationObserver

This means you only pay for what you use. If your page only uses fx-* attributes, only the fmtX module is loaded.

fmtX — Formatting

Prefix: fx-*

Format text, numbers, dates, and phone numbers with simple attributes.

Currency

<span fx-format="currency">1299.99</span>
<!-- Output: $1,299.99 -->

<span fx-format="currency" fx-currency="EUR">1299.99</span>
<!-- Output: €1,299.99 -->

<span fx-format="currency" fx-currency="JPY">1299</span>
<!-- Output: ¥1,299 -->

Phone Numbers

<span fx-format="phone">5551234567</span>
<!-- Output: (555) 123-4567 -->

<span fx-format="phone" fx-phone-format="intl">15551234567</span>
<!-- Output: +1 555 123 4567 -->

Dates

<span fx-format="date">2024-03-15</span>
<!-- Output: 3/15/2024 -->

<span fx-format="date" fx-date-format="long">2024-03-15</span>
<!-- Output: March 15, 2024 -->

<span fx-format="date" fx-date-format="relative">2024-03-15</span>
<!-- Output: 2 days ago -->

Numbers

<span fx-format="number">1234567</span>
<!-- Output: 1,234,567 -->

<span fx-format="number" fx-decimals="2">1234.5</span>
<!-- Output: 1,234.50 -->

<span fx-format="percent">0.156</span>
<!-- Output: 15.6% -->

accX — Accessibility

Prefix: ax-*

Enhance accessibility with ARIA attributes and keyboard navigation.

<!-- Accessible button with label -->
<button ax-label="Close dialog">×</button>

<!-- Accessible image -->
<img src="chart.png" ax-desc="Sales chart showing 20% growth">

<!-- Skip to main content link -->
<a href="#main" ax-skip-link>Skip to content</a>

<!-- Live region for dynamic updates -->
<div ax-live="polite">3 items in cart</div>

loadX — Loading States

Prefix: lx-*

Add loading indicators, skeletons, and progress states.

<!-- Loading spinner -->
<button lx-loading="true">Submit</button>

<!-- Skeleton loading -->
<div lx-skeleton="text">Loading content...</div>
<div lx-skeleton="card"></div>

<!-- Progress bar -->
<div lx-progress="75"></div>

navX — Navigation

Prefix: nx-*

Client-side routing and navigation enhancement.

<!-- SPA-style navigation -->
<a href="/about" nx-link>About Us</a>

<!-- Active state on current page -->
<nav>
  <a href="/" nx-link nx-active-class="current">Home</a>
  <a href="/products" nx-link nx-active-class="current">Products</a>
</nav>

<!-- Page content container -->
<main nx-outlet></main>

dragX — Drag & Drop

Prefix: dx-*

Make elements draggable with drop zone support.

<!-- Draggable item -->
<div dx-draggable="card">Drag me</div>

<!-- Drop zone -->
<div dx-drop-zone="cards">Drop cards here</div>

<!-- Sortable list -->
<ul dx-sortable>
  <li dx-draggable>Item 1</li>
  <li dx-draggable>Item 2</li>
  <li dx-draggable>Item 3</li>
</ul>

bindX — Data Binding

Prefix: bx-*

Reactive data binding for dynamic content.

<!-- Two-way binding -->
<input type="text" bx-model="name">
<p>Hello, <span bx-text="name"></span>!</p>

<!-- Conditional display -->
<div bx-show="isLoggedIn">Welcome back!</div>

<!-- List rendering -->
<ul bx-for="item in items">
  <li bx-text="item.name"></li>
</ul>

<!-- Event handling -->
<button bx-on:click="handleClick">Click me</button>

tableX — Tables

Prefix: tx-*

Enhanced tables with sorting, filtering, and pagination.

<table tx-sortable>
  <thead>
    <tr>
      <th tx-sort="name">Name</th>
      <th tx-sort="date" tx-sort-type="date">Date</th>
      <th tx-sort="price" tx-sort-type="number">Price</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Widget</td>
      <td>2024-03-15</td>
      <td>29.99</td>
    </tr>
    <!-- More rows -->
  </tbody>
</table>

<!-- With pagination -->
<table tx-sortable tx-paginate="10">
  <!-- ... -->
</table>

smartX — Auto-Format

Prefix: sx-*

Automatically detect and format content based on patterns.

<!-- Auto-detect formatting -->
<span sx-auto>$1,234.56</span>
<span sx-auto>(555) 123-4567</span>
<span sx-auto>2024-03-15</span>
<span sx-auto>user@example.com</span>

<!-- Smart links -->
<span sx-linkify>Visit https://example.com</span>

Framework Compatibility

genX works with any framework because it operates on the DOM after rendering. Use it alongside your existing stack.

React

function ProductCard({ price }) {
  return (
    <div className="product">
      <span fx-format="currency">{price}</span>
    </div>
  );
}

Vue

<template>
  <div class="product">
    <span fx-format="currency">{{ price }}</span>
  </div>
</template>

htmx

genX and htmx complement each other perfectly:

<!-- htmx loads content, genX formats it -->
<div hx-get="/api/products" hx-trigger="load">
  <!-- Server returns: <span fx-format="currency">29.99</span> -->
  <!-- genX automatically formats to: $29.99 -->
</div>

Server-Side (Django, Rails, Laravel, PHP)

genX is ideal for server-rendered HTML. Your backend outputs raw values, genX formats them:

<!-- Django -->
<span fx-format="currency">{{ product.price }}</span>

<!-- Rails -->
<span fx-format="currency"><%= product.price %></span>

<!-- Laravel -->
<span fx-format="currency">{{ $product->price }}</span>

<!-- PHP -->
<span fx-format="currency"><?= $product['price'] ?></span>

Troubleshooting

Elements Not Formatting

Check:

Script is loading (check browser console for errors)
Script has defer attribute
Attribute names are correct (fx-format, not fx_format or data-fx-format)
Values are valid (numbers for currency, ISO dates for dates)

Dynamic Content Not Processing

Elements added via JavaScript should process automatically. If not:

Verify elements are added to the DOM, not just created
Check for JavaScript errors blocking execution
Ensure MutationObserver is supported (all modern browsers)

Table Sorting Not Working

Check:

tx-sortable class is on <th> elements
Table has proper <thead> and <tbody> structure
No conflicting JavaScript handling click events

Common Console Errors

Error	Fix
`genX is not defined`	Check script URL and network tab
`Invalid date`	Use ISO format: `2024-03-15`
`NaN`	Ensure numeric values are clean

Browser Support

genX supports all modern browsers:

Chrome 90+
Firefox 88+
Safari 14+
Edge 90+

Requirements: ES6+, Proxy, MutationObserver, async/await

Performance

genX is designed for speed:

Bootloader: <5ms to scan 1000 elements
Parsing: <100ms for 1000 elements
Operations: <16ms (60 FPS target)
Module init: <105ms total bootstrap

The bootloader uses MutationObserver to watch for dynamic content, so elements added after page load are automatically processed.