XNPV function

PRO BASIC

The XNPV function in Jspreadsheet Formulas Pro is a financial formula that helps you calculate the net present value (NPV) of an investment. This is done by considering a series of irregular cash flows tied to specific dates and a discount rate. Essentially, it helps to understand the value of future cash flows in today's money terms. This function is particularly useful in investment analysis, helping to determine the profitability or viability of a potential investment.

Documentation

Calculates the net present value of an investment based on a series of irregular cash flows tied to specific dates and a discount rate.

Syntax

XNPV(rate, values, dates)

Parameter	Description
`rate`	The discount rate to apply to the cash flows, expressed as a decimal.
`values`	An array or range of cells representing the series of cash flows.
`dates`	An array or range of cells representing the dates corresponding to each cash flow.

Behavior

The XNPV function calculates the net present value of an investment by using a discount rate and a series of future payments (negative values) and income (positive values).

Empty cells: If any of the value or date arrays are empty, the XNPV function will return an error.
Text: The XNPV function cannot handle text. If any of the date or value arrays contain text, it will return an error.
Booleans: Boolean values are not handled by XNPV. If boolean values are included in the value or date arrays, it will return an error.
Errors: If an error occurs in the value or date arrays, the XNPV function will return that error.
Dates: They must be valid Jspreadsheet date values in ISO format (YYYY-MM-DD). If not, XNPV will return a #NUM! error.

Common Errors

Error	Description
#VALUE!	If the provided discount rate is non-numeric
#NUM!	occurs if the dates are not chronological, contain invalid date formats, or if the first cash flow is not negative (initial investment).
#REF!	If any of the cell references are not valid
#N/A	If the dates and values arrays have different lengths

Best Practices

Always ensure that the dates provided are in chronological order and are valid Jspreadsheet date values (YYYY-MM-DD).

Make sure the value and date arrays have the same length.

Avoid including text, boolean values or error values in the value or date arrays as XNPV does not support these.

The discount rate should be in decimal form, not a percentage. For example, use 0.05 for a 5% discount rate.

Usage

A few examples using the XNPV function.

XNPV(0.05, [-1000, 250, 250, 250, 250, 250], 
     ["2022-01-01","2023-01-01","2024-01-01","2025-01-01","2026-01-01","2027-01-01"])  
// Investment of -1000 with annual returns of 250 over five years, discounted at 5%

XNPV(0.1, [-5000, 1000, 2000, 3000], 
     ["2019-01-01","2020-01-01","2021-01-01","2022-01-01"])  
// Initial outflow of -5000 with increasing yearly inflows, discounted at 10%

XNPV(0.06, [10000, -1500, -1500, -1500, -1500], 
     ["2021-01-01","2022-01-01","2023-01-01","2024-01-01","2025-01-01"])  
// Loan scenario: upfront inflow of 10000 with annual repayments of -1500, discounted at 6%

Interactive Spreadsheet Demo

<html>
<script src="https://jspreadsheet.com/v11/jspreadsheet.js"></script>
<script src="https://jsuites.net/v5/jsuites.js"></script>
<link rel="stylesheet" href="https://jsuites.net/v5/jsuites.css" type="text/css" />
<link rel="stylesheet" href="https://jspreadsheet.com/v11/jspreadsheet.css" type="text/css" />

<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Material+Icons" />
<script src="https://cdn.jsdelivr.net/npm/@jspreadsheet/formula-pro/dist/index.min.js"></script>

<div id="spreadsheet"></div>

<script>
// Set your JSS license key (The following key only works for one day)
jspreadsheet.setLicense('NjJlZjE0YTMzODMzYTJlMDEwNDc5NmVlZDJhYTA1MzgxMzc2ZDdkZDBiNmYyZGUwN2QwNGIwMDkzNTAxY2UxNDJhYmVmOWI2NGNiMzExODJiMDM0NjMxMjA4NzNlMGY4MzFiNjJjODU4NjcxYTEyNjU1MjJkNjIwMmU1MjNiMGMsZXlKamJHbGxiblJKWkNJNklpSXNJbTVoYldVaU9pSktjM0J5WldGa2MyaGxaWFFpTENKa1lYUmxJam94TnpVNE56YzBOekExTENKa2IyMWhhVzRpT2xzaWFuTndjbVZoWkhOb1pXVjBMbU52YlNJc0ltTnZaR1Z6WVc1a1ltOTRMbWx2SWl3aWFuTm9aV3hzTG01bGRDSXNJbU56WWk1aGNIQWlMQ0p6ZEdGamEySnNhWFI2TG1sdklpd2lkMlZpWTI5dWRHRnBibVZ5TG1sdklpd2lkMlZpSWl3aWJHOWpZV3hvYjNOMElsMHNJbkJzWVc0aU9pSXpOQ0lzSW5OamIzQmxJanBiSW5ZM0lpd2lkamdpTENKMk9TSXNJbll4TUNJc0luWXhNU0lzSW1Ob1lYSjBjeUlzSW1admNtMXpJaXdpWm05eWJYVnNZU0lzSW5CaGNuTmxjaUlzSW5KbGJtUmxjaUlzSW1OdmJXMWxiblJ6SWl3aWFXMXdiM0owWlhJaUxDSmlZWElpTENKMllXeHBaR0YwYVc5dWN5SXNJbk5sWVhKamFDSXNJbkJ5YVc1MElpd2ljMmhsWlhSeklpd2lZMnhwWlc1MElpd2ljMlZ5ZG1WeUlpd2ljMmhoY0dWeklpd2labTl5YldGMElsMHNJbVJsYlc4aU9uUnlkV1Y5');

// Set the extensions
jspreadsheet.setExtensions({ formula });

// Create a new spreadsheet
jspreadsheet(document.getElementById('spreadsheet'), {
  worksheets: [{
    data: [
    [
        "Date",
        "Cash Flow",
        "NPV Calculation"
    ],
    [
        "2024-01-01",
        -10000,
        "=XNPV(0.08,B1:B5,A1:A5)"
    ],
    [
        "2024-06-15",
        2500
    ],
    [
        "2024-12-31",
        3000
    ],
    [
        "2025-12-31",
        4500
    ]
]
  }]
});
</script>
</html>

import React, { useRef } from "react";
import { Spreadsheet, Worksheet, jspreadsheet } from "@jspreadsheet/react";
import formula from "@jspreadsheet/formula-pro";
import "jsuites/dist/jsuites.css";
import "jspreadsheet/dist/jspreadsheet.css";

// Set license
jspreadsheet.setLicense('NjJlZjE0YTMzODMzYTJlMDEwNDc5NmVlZDJhYTA1MzgxMzc2ZDdkZDBiNmYyZGUwN2QwNGIwMDkzNTAxY2UxNDJhYmVmOWI2NGNiMzExODJiMDM0NjMxMjA4NzNlMGY4MzFiNjJjODU4NjcxYTEyNjU1MjJkNjIwMmU1MjNiMGMsZXlKamJHbGxiblJKWkNJNklpSXNJbTVoYldVaU9pSktjM0J5WldGa2MyaGxaWFFpTENKa1lYUmxJam94TnpVNE56YzBOekExTENKa2IyMWhhVzRpT2xzaWFuTndjbVZoWkhOb1pXVjBMbU52YlNJc0ltTnZaR1Z6WVc1a1ltOTRMbWx2SWl3aWFuTm9aV3hzTG01bGRDSXNJbU56WWk1aGNIQWlMQ0p6ZEdGamEySnNhWFI2TG1sdklpd2lkMlZpWTI5dWRHRnBibVZ5TG1sdklpd2lkMlZpSWl3aWJHOWpZV3hvYjNOMElsMHNJbkJzWVc0aU9pSXpOQ0lzSW5OamIzQmxJanBiSW5ZM0lpd2lkamdpTENKMk9TSXNJbll4TUNJc0luWXhNU0lzSW1Ob1lYSjBjeUlzSW1admNtMXpJaXdpWm05eWJYVnNZU0lzSW5CaGNuTmxjaUlzSW5KbGJtUmxjaUlzSW1OdmJXMWxiblJ6SWl3aWFXMXdiM0owWlhJaUxDSmlZWElpTENKMllXeHBaR0YwYVc5dWN5SXNJbk5sWVhKamFDSXNJbkJ5YVc1MElpd2ljMmhsWlhSeklpd2lZMnhwWlc1MElpd2ljMlZ5ZG1WeUlpd2ljMmhoY0dWeklpd2labTl5YldGMElsMHNJbVJsYlc4aU9uUnlkV1Y5');

// Set the extensions
jspreadsheet.setExtensions({ formula });

export default function App() {
    // Spreadsheet array of worksheets
    const spreadsheet = useRef();

    // Worksheet data
    const data = [
    [
        "Date",
        "Cash Flow",
        "NPV Calculation"
    ],
    [
        "2024-01-01",
        -10000,
        "=XNPV(0.08,B1:B5,A1:A5)"
    ],
    [
        "2024-06-15",
        2500
    ],
    [
        "2024-12-31",
        3000
    ],
    [
        "2025-12-31",
        4500
    ]
];

    // Render component
    return (
        <Spreadsheet ref={spreadsheet}>
            <Worksheet data={data} />
        </Spreadsheet>
    );
}

<template>
    <Spreadsheet ref="spreadsheet">
        <Worksheet :data="data" />
    </Spreadsheet>
</template>

<script>
import { Spreadsheet, Worksheet, jspreadsheet } from "@jspreadsheet/vue";
import "jsuites/dist/jsuites.css";
import "jspreadsheet/dist/jspreadsheet.css";
import formula from "@jspreadsheet/formula-pro";

// Set license
jspreadsheet.setLicense('NjJlZjE0YTMzODMzYTJlMDEwNDc5NmVlZDJhYTA1MzgxMzc2ZDdkZDBiNmYyZGUwN2QwNGIwMDkzNTAxY2UxNDJhYmVmOWI2NGNiMzExODJiMDM0NjMxMjA4NzNlMGY4MzFiNjJjODU4NjcxYTEyNjU1MjJkNjIwMmU1MjNiMGMsZXlKamJHbGxiblJKWkNJNklpSXNJbTVoYldVaU9pSktjM0J5WldGa2MyaGxaWFFpTENKa1lYUmxJam94TnpVNE56YzBOekExTENKa2IyMWhhVzRpT2xzaWFuTndjbVZoWkhOb1pXVjBMbU52YlNJc0ltTnZaR1Z6WVc1a1ltOTRMbWx2SWl3aWFuTm9aV3hzTG01bGRDSXNJbU56WWk1aGNIQWlMQ0p6ZEdGamEySnNhWFI2TG1sdklpd2lkMlZpWTI5dWRHRnBibVZ5TG1sdklpd2lkMlZpSWl3aWJHOWpZV3hvYjNOMElsMHNJbkJzWVc0aU9pSXpOQ0lzSW5OamIzQmxJanBiSW5ZM0lpd2lkamdpTENKMk9TSXNJbll4TUNJc0luWXhNU0lzSW1Ob1lYSjBjeUlzSW1admNtMXpJaXdpWm05eWJYVnNZU0lzSW5CaGNuTmxjaUlzSW5KbGJtUmxjaUlzSW1OdmJXMWxiblJ6SWl3aWFXMXdiM0owWlhJaUxDSmlZWElpTENKMllXeHBaR0YwYVc5dWN5SXNJbk5sWVhKamFDSXNJbkJ5YVc1MElpd2ljMmhsWlhSeklpd2lZMnhwWlc1MElpd2ljMlZ5ZG1WeUlpd2ljMmhoY0dWeklpd2labTl5YldGMElsMHNJbVJsYlc4aU9uUnlkV1Y5');

// Set the extensions
jspreadsheet.setExtensions({ formula });

export default {
    components: {
        Spreadsheet,
        Worksheet,
    },
    data() {
        // Worksheet data
        const data = [
    [
        "Date",
        "Cash Flow",
        "NPV Calculation"
    ],
    [
        "2024-01-01",
        -10000,
        "=XNPV(0.08,B1:B5,A1:A5)"
    ],
    [
        "2024-06-15",
        2500
    ],
    [
        "2024-12-31",
        3000
    ],
    [
        "2025-12-31",
        4500
    ]
]

        return {
            data
        };
    }
}
</script>

import { Component, ViewChild, ElementRef } from "@angular/core";
import jspreadsheet from "jspreadsheet";
import * as formula from "@jspreadsheet/formula-pro";

// Set your JSS license key (The following key only works for one day)
jspreadsheet.setLicense('NjJlZjE0YTMzODMzYTJlMDEwNDc5NmVlZDJhYTA1MzgxMzc2ZDdkZDBiNmYyZGUwN2QwNGIwMDkzNTAxY2UxNDJhYmVmOWI2NGNiMzExODJiMDM0NjMxMjA4NzNlMGY4MzFiNjJjODU4NjcxYTEyNjU1MjJkNjIwMmU1MjNiMGMsZXlKamJHbGxiblJKWkNJNklpSXNJbTVoYldVaU9pSktjM0J5WldGa2MyaGxaWFFpTENKa1lYUmxJam94TnpVNE56YzBOekExTENKa2IyMWhhVzRpT2xzaWFuTndjbVZoWkhOb1pXVjBMbU52YlNJc0ltTnZaR1Z6WVc1a1ltOTRMbWx2SWl3aWFuTm9aV3hzTG01bGRDSXNJbU56WWk1aGNIQWlMQ0p6ZEdGamEySnNhWFI2TG1sdklpd2lkMlZpWTI5dWRHRnBibVZ5TG1sdklpd2lkMlZpSWl3aWJHOWpZV3hvYjNOMElsMHNJbkJzWVc0aU9pSXpOQ0lzSW5OamIzQmxJanBiSW5ZM0lpd2lkamdpTENKMk9TSXNJbll4TUNJc0luWXhNU0lzSW1Ob1lYSjBjeUlzSW1admNtMXpJaXdpWm05eWJYVnNZU0lzSW5CaGNuTmxjaUlzSW5KbGJtUmxjaUlzSW1OdmJXMWxiblJ6SWl3aWFXMXdiM0owWlhJaUxDSmlZWElpTENKMllXeHBaR0YwYVc5dWN5SXNJbk5sWVhKamFDSXNJbkJ5YVc1MElpd2ljMmhsWlhSeklpd2lZMnhwWlc1MElpd2ljMlZ5ZG1WeUlpd2ljMmhoY0dWeklpd2labTl5YldGMElsMHNJbVJsYlc4aU9uUnlkV1Y5');

// Set the extensions
jspreadsheet.setExtensions({ formula });

@Component({
    standalone: true,
    selector: "app-root",
    template: `<div #spreadsheet></div>`
})
export class AppComponent {
    @ViewChild("spreadsheet") spreadsheet: ElementRef;
    // Worksheets
    worksheets: jspreadsheet.worksheetInstance[];

    // Create a new data grid
    ngAfterViewInit() {
        // Create spreadsheet
        this.worksheets = jspreadsheet(this.spreadsheet.nativeElement, {
            worksheets: [{
                data: [
    [
        "Date",
        "Cash Flow",
        "NPV Calculation"
    ],
    [
        "2024-01-01",
        -10000,
        "=XNPV(0.08,B1:B5,A1:A5)"
    ],
    [
        "2024-06-15",
        2500
    ],
    [
        "2024-12-31",
        3000
    ],
    [
        "2025-12-31",
        4500
    ]
]
            }]
        });
    }
}

Edit this page on GitHub