jQuery Calx 3.0
Modern spreadsheet-like calculation engine for the web
📖 Introduction
jQuery Calx 3.0 is a complete TypeScript rewrite of the popular jQuery Calx plugin. It transforms your HTML forms into powerful spreadsheet-like calculators with real-time formula evaluation, cell dependencies, and Excel-compatible functions.
Whether you're building a mortgage calculator, invoice generator, order form, or any interactive calculation interface, jQuery Calx provides an intuitive and powerful solution.
✨ What's New in 3.0
🔧 TypeScript Rewrite
Complete rewrite in TypeScript for better type safety and developer experience
⚡ Dynamic Precedents
Optimized dependency tracking with pattern-based precedent detection
💰 Input Masking
Built-in formatters with parse/format methods for currency, percentage, and more
🎨 Conditional Styling
Apply CSS styles based on cell values with data-style-if attribute
🏷️ Named Variables
Use readable variable names with data-var attribute (e.g., TAX, DISCOUNT)
📊 Multi-Sheet Support
Work with multiple calculation sheets and cross-sheet references
🚀 Auto CALX Addresses
Formula-only cells automatically assigned addresses (CALX1, CALX2, etc.)
📱 Responsive Design
Mobile-friendly examples and modern UI components
📦 Installation
Via CDN (Coming Soon)
<!-- jQuery (required) -->
<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
<!-- jQuery Calx -->
<script src="https://cdn.jsdelivr.net/npm/@xsanisty/calxjs@3.0.0/dist/jquery.calx.js"></script>Via NPM
🚀 Quick Start
Basic Example
<form id="calculator">
<input type="number" data-cell="A1" value="10">
<input type="number" data-cell="A2" value="20">
<input type="text" data-cell="A3" data-formula="A1+A2" readonly>
</form>
<script>
$('#calculator').calx();
</script>With Formatting
<form id="invoice">
<input data-cell="A1" data-var="PRICE" value="100" data-format="currency">
<input data-cell="A2" data-var="QTY" value="5">
<input data-cell="A3" data-var="TAX" value="0.08" data-format="percent">
<input data-formula="PRICE*QTY*(1+TAX)" data-format="currency" readonly>
</form>
<script>
$('#invoice').calx({ autoCalculate: true });
</script>🔄 Migration from 2.x to 3.0
✅ Backward Compatible
jQuery Calx 3.0 maintains full backward compatibility with 2.x. Your existing code will continue to work without changes.
1. TypeScript Rewrite
What changed: Complete rewrite in TypeScript with improved type safety and modern architecture.
The jQuery plugin API remains the same, but the underlying implementation is now TypeScript-based with better maintainability and extensibility.
2. Enhanced Style Formatters
Improved: Style formatters now properly reset styles when conditions change.
<!-- Conditional styling (existed in 2.x, improved in 3.0) -->
<input data-formula="Revenue-Expenses" data-style-if="negative">
<!-- Custom style formatter -->
$.calx.registerStyleFormatter('myStyle', function(value) {
if (value > 100) return { color: 'red', fontWeight: 'bold' };
return { color: '' }; // Properly resets in 3.0
});3. Improved Parser
What changed: Updated formula parser with better error handling and support for more complex expressions.
All existing formulas continue to work, with additional support for nested functions and complex calculations.
4. Named Variables (Available since 2.0)
Use data-var for readable cell references. This feature existed in 2.x and continues to work in 3.0.
<input data-cell="A1" data-var="PRINCIPAL" value="250000">
<input data-cell="A2" data-var="RATE" value="6.5">
<input data-formula="PMT(RATE/100/12, 360, -PRINCIPAL)" readonly>🎯 Key Features
Supported Data Attributes
| Attribute | Description | Example |
|---|---|---|
data-cell |
Cell address (A1, B5, etc.) | data-cell="A1" |
data-formula |
Formula expression | data-formula="A1+A2" |
data-format |
Formatter name | data-format="currency" |
data-type |
Data type (number, text, boolean) | data-type="number" |
data-var |
Named variable | data-var="TAX" |
data-style-if |
Conditional style formatter | data-style-if="negative" |
data-sheet |
Sheet name for multi-sheet | data-sheet="Sales" |
Built-in Formatters
| Formatter | Description | Input → Output |
|---|---|---|
currency |
Currency formatting with $ and commas | $4000 → $4,000.00 |
percent |
Percentage with % symbol | 25% → 25.00% |
number |
Number with 2 decimals | 1234.5 → 1234.50 |
integer |
Rounded integer | 123.7 → 124 |
text |
Plain text | Hello → Hello |
Built-in Style Formatters
| Style Formatter | Condition | Style Applied |
|---|---|---|
negative |
value < 0 | color: red |
positive |
value > 0 | color: green |
zero |
value === 0 | color: gray |
📚 API Reference
Initialization Options
$('#form').calx({
autoCalculate: true, // Auto-calculate on input change
data: { // Initial cell data
A1: { value: 100, format: 'currency' }
},
variables: { // Named variables
TAX: 'A1'
},
functions: { // Custom functions
DOUBLE: function(x) { return x * 2; }
}
});Methods
| Method | Description | Example |
|---|---|---|
getCellValue(address) |
Get cell value | $('#form').calx('getCellValue', 'A1') |
setCellValue(address, value) |
Set cell value | $('#form').calx('setCellValue', 'A1', 100) |
getCell(address) |
Get cell object | $('#form').calx('getCell', 'A1') |
calculate() |
Trigger calculation | $('#form').calx('calculate') |
getSheet() |
Get sheet object | $('#form').calx('getSheet') |
Registering Custom Formatters
$.calx.registerFormatter('phone', {
format: function(value) {
// Format: (123) 456-7890
return '(' + value.slice(0,3) + ') ' +
value.slice(3,6) + '-' + value.slice(6);
},
parse: function(input) {
// Remove formatting
return input.replace(/[^\d]/g, '');
}
});Registering Custom Functions
$.calx.registerFunction('DISCOUNT', function(price, percent) {
return price * (1 - percent);
});
// Usage: data-formula="DISCOUNT(A1, 0.15)"📝 Live Examples
Explore interactive examples to see jQuery Calx in action:
🤝 Contributing
jQuery Calx is open source! Contributions, bug reports, and feature requests are welcome on GitHub.
Legacy Documentation: Looking for jQuery Calx 2.x documentation? Visit www.xsanisty.com/project/calx2/