How to Build Custom Asynchronous Spreadsheet Formulas in JavaScript Apps

Sometimes, you want your formulas in SpreadJS (JavaScript Spreadsheet) to do more than simple calculations, like maybe call a web service or process data asynchronously. In fact, we were asked how to do this by an AI company that wanted to query an AI model from a function, which is a pretty cool use case. Fortunately, SpreadJS lets you build custom functions that support both asynchronous operations and cell references.

Let’s walk through how to build one.

Our scenario: Allow a user to ask a question in a spreadsheet cell that references data from another other cell, which will be sent to an AI model to answer. Note we are just going to render the final AI query as the result. But in reality, you would send it to an external service to get the real result. 

Follow Along with the Live Demo Sample Here!

Steps to Create a Custom Async Function in JavaScript Spreadsheets

• Step 1: Set Up a JavaScript Workbook
• Step 2: Define an Async Custom Function
• Step 3: Implement Asynchronous Evaluation
• Step 4: Register and Use the Custom Formula
• How It Works
• Example Output
• Try It Yourself

Download a Trial of the Industry Leading JavaScript Spreadsheet, SpreadJS, Today!

Step 1: Set Up a JavaScript Workbook

Start by creating a SpreadJS workbook and getting a reference to the first sheet:

var spread = new GC.Spread.Sheets.Workbook(document.getElementById("ss"));
var sheet = spread.getSheet(0);

Then add a few labels and sample data:

sheet.setValue(1, 1, 'Custom Function');
sheet.setValue(7, 1, "New York");
sheet.setColumnWidth(1, 120);
sheet.setColumnWidth(2, 300);

Step 2: Define an Async Custom Function

To define a custom formula, create a new AsyncFunction class that inherits from
GC.Spread.CalcEngine.Functions.AsyncFunction.  This allows your function to return results asynchronously (for example, from an API call).

var AskMeFunction = function() {};
AskMeFunction.prototype = new GC.Spread.CalcEngine.Functions.AsyncFunction("AskMe", 2, 2);

Here "AskMe" is the formula name, and 2, 2 specify the minimum and maximum number of parameters.

Add a default value (used while waiting for async results):

AskMeFunction.prototype.defaultValue = function () {
    return "Thinking...";
};

Check out the Asynchronous Functions Documentation here to learn more.

Step 3: Implement Asynchronous Evaluation

Inside evaluateAsync, you can call a service or perform an async operation.
In this demo, a setTimeout simulates a 2-second delay, but you could replace it with a real fetch() or XMLHttpRequest call.

AskMeFunction.prototype.evaluateAsync = function (context) {   
    var args = arguments;

    setTimeout(function () {
        if (args.length === 3) {
            result = "You asked: " + args[1] + " " + args[2] + "?";
        }
        context.setAsyncResult(result);
    }, 2000);
};

Notice that args[1] and args[2] correspond to your formula parameters, including any cell references (SpreadJS automatically resolves them before evaluation). We skip args[0] since this is reserved as the context. 

Step 4: Register and Use the Custom Formula

Finally, register your function and use it in a cell just like any other formula:

var AskMe = new AskMeFunction();
sheet.addCustomFunction(AskMe);

// display the formula and result
sheet.setValue(3, 1, 'Formula');
sheet.setValue(3, 2, '=AskMe("What is the capital of", B8)');
sheet.setValue(4, 1, 'Result');
sheet.setFormula(4, 2, '=AskMe("What is the capital of", B8)');

When the sheet recalculates, you’ll briefly see “Thinking...” before the async result appears.

🧠 How It Works

• SpreadJS calls evaluateAsync() whenever the formula runs.
• It passes in resolved argument values (even if they reference other cells).
• The function can perform asynchronous operations (like API calls).
• When the result is ready, call context.setAsyncResult(value) to update the cell.

✅ Example Output

Remember: we are just going to render the final AI query as the result. But in reality, you would send it to an external service to get the real result. 

If cell B8 contains "New York", the formula:

=AskMe("What is the capital of", B8)

will eventually display:

You asked: What is the capital of New York?

🔗 Try It Yourself

• Explore a live JavaScript spreadsheet sample that follows this tutorials steps: SpreadJS Custom Async Formula Demo
• To learn more, see our Asynchronous Functions Documentation or online Async Function Demo Sample. 
• We also have a premade AI Assistant if you want to use AI formulas in SpreadJS today!

Download a Trial of the Industry Leading JavaScript Spreadsheet, SpreadJS, Today!