Nullish coalescing operator (??)

BaselineWidely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2020.

Thenullish coalescing (??) operator is a logicaloperator that returns its right-hand side operand when its left-hand side operand isnull orundefined, and otherwise returns its left-hand sideoperand.

Try it

const foo = null ?? "default string";console.log(foo);// Expected output: "default string"const baz = 0 ?? 42;console.log(baz);// Expected output: 0

Syntax

leftExpr ?? rightExpr

Description

The nullish coalescing operator can be seen as a special case of thelogical OR (||) operator. The latter returns the right-hand side operand if the left operand isanyfalsy value, not onlynull orundefined. In other words, if you use|| to provide some default value to another variablefoo, you may encounter unexpected behaviors if you consider some falsy values as usable (e.g.,'' or0). Seebelow for more examples.

The nullish coalescing operator has the fifth-lowestoperator precedence, directly lower than|| and directly higher than theconditional (ternary) operator.

It is not possible to combine both the AND (&&) and OR operators (||) directly with??. Asyntax error will be thrown in such cases.

null || undefined ?? "foo"; // raises a SyntaxErrortrue && undefined ?? "foo"; // raises a SyntaxError

Instead, provide parenthesis to explicitly indicate precedence:

(null || undefined) ?? "foo"; // returns "foo"

Examples

Using the nullish coalescing operator

In this example, we will provide default values but keep values other thannull orundefined.

const nullValue = null;const emptyText = ""; // falsyconst someNumber = 42;const valA = nullValue ?? "default for A";const valB = emptyText ?? "default for B";const valC = someNumber ?? 0;console.log(valA); // "default for A"console.log(valB); // "" (as the empty string is not null or undefined)console.log(valC); // 42

Assigning a default value to a variable

Earlier, when one wanted to assign a default value to a variable, a common pattern was to use the logical OR operator (||):

let foo;// foo is never assigned any value so it is still undefinedconst someDummyText = foo || "Hello!";

However, due to|| being a boolean logical operator, the left-hand-side operand was coerced to a boolean for the evaluation and anyfalsy value (including0,'',NaN,false, etc.) was not returned. This behavior may cause unexpected consequences if you consider0,'', orNaN as valid values.

const count = 0;const text = "";const qty = count || 42;const message = text || "hi!";console.log(qty); // 42 and not 0console.log(message); // "hi!" and not ""

The nullish coalescing operator avoids this pitfall by only returning the second operand when the first one evaluates to eithernull orundefined (but no other falsy values):

const myText = ""; // An empty string (which is also a falsy value)const notFalsyText = myText || "Hello world";console.log(notFalsyText); // Hello worldconst preservingFalsy = myText ?? "Hi neighborhood";console.log(preservingFalsy); // '' (as myText is neither undefined nor null)

Short-circuiting

Like the 'OR' and 'AND' logical operators, the right-hand side expression is not evaluated if the left-hand side proves to be neithernull norundefined.

function a() {  console.log("a was called");  return undefined;}function b() {  console.log("b was called");  return false;}function c() {  console.log("c was called");  return "foo";}console.log(a() ?? c());// Logs "a was called" then "c was called" and then "foo"// as a() returned undefined so both expressions are evaluatedconsole.log(b() ?? c());// Logs "b was called" then "false"// as b() returned false (and not null or undefined), the right// hand side expression was not evaluated

Relationship with the optional chaining operator (?.)

The nullish coalescing operator treatsundefined andnull as specific values. So does theoptional chaining operator (?.), which is useful to access a property of an object which may benull orundefined. Combining them, you can safely access a property of an object which may be nullish and provide a default value if it is.

const foo = { someFooProp: "hi" };console.log(foo.someFooProp?.toUpperCase() ?? "not available"); // "HI"console.log(foo.someBarProp?.toUpperCase() ?? "not available"); // "not available"