Suggest an edit

Improve this article

Refine the answer for “The nullish coalescing operator (??)”. Your changes go to moderation before they’re published.

Approval required

Content

What you’re changing

Title (EN)

Short answer (EN)

Shown above the full answer for quick recall.

Answer (EN)

**The `??` (nullish coalescing) operator returns its left operand when that operand is neither `null` nor `undefined`, and returns the right one otherwise.** It is the way to supply a default value for a genuinely missing value rather than for any falsy value.

## Theory

### TL;DR
- `a ?? b`: if `a` is not `null` and not `undefined`, `a` is returned, otherwise `b`.
- `||` fires on every falsy value, `??` only on nullish ones (`null`, `undefined`).
- That is why `0 ?? 100` gives `0`, while `0 || 100` gives `100`.
- The right operand is evaluated only when needed, so this is short-circuiting too.
- `??` cannot be mixed with `&&` or `||` without parentheses, it is a `SyntaxError`.

### Quick example
```javascript
const name = null;
const displayName = name ?? 'Guest';

console.log(displayName); // "Guest"

null ?? 'default'      // "default"
undefined ?? 'default' // "default"
0 ?? 100               // 0
'' ?? 'text'           // ""
false ?? true          // false
```

### Syntax and how to read the expression
```javascript
a ?? b
```

Read it as: "if `a` is not `null` and not `undefined`, return `a`, otherwise return `b`".

Formally it is equivalent to this:

```javascript
value1 ?? value2
// if value1 !== null && value1 !== undefined -> return value1
// otherwise -> return value2
```

Like `||` and `&&`, the `??` operator short-circuits: the right operand is not evaluated when the left one is already usable.

### Comparison with `||` (logical OR)
The operators look alike, but the difference is fundamental: `||` treats **every falsy value** (`0`, `''`, `false`, `NaN`, `null`, `undefined`) as "empty", while `??` reacts **only to `null` and `undefined`**.

```javascript
const a = 0;

console.log(a || 100); // 100, because 0 is falsy
console.log(a ?? 100); // 0,   because 0 is not nullish
```

In other words, `??` **preserves** values such as `0`, `false` and `''`.

| Value of `a` | `a \|\| 'default'` | `a ?? 'default'` |
| --- | --- | --- |
| `undefined` | `'default'` | `'default'` |
| `null` | `'default'` | `'default'` |
| `0` | `'default'` | `0` |
| `false` | `'default'` | `false` |
| `''` | `'default'` | `''` |
| `'text'` | `'text'` | `'text'` |

### Practical examples
A value from a settings object, where `false` is a valid user choice:

```javascript
const settings = {
  theme: null,
  notifications: false,
};

const theme = settings.theme ?? 'light';
const notifications = settings.notifications ?? true;

console.log(theme);         // "light"
console.log(notifications); // false, the value was not replaced
```

`notifications` did not become `true`, because `false` is neither `null` nor `undefined`.

A default for a function argument that may be omitted or explicitly `null`:

```javascript
function greet(name) {
  const user = name ?? 'Guest';
  console.log(`Hello, ${user}!`);
}

greet('Maria'); // "Hello, Maria!"
greet(null);    // "Hello, Guest!"
greet();        // "Hello, Guest!"
```

Typical places where it is used:

```javascript
const page = config.page ?? 1;                       // a default value
const userName = response.data.name ?? 'Anonymous';  // data from an API
console.log(`Hello, ${user.name ?? 'guest'}!`);      // rendering in the UI
```

### Precedence and mandatory parentheses
`??` cannot be mixed with `&&` or `||` in one expression without parentheses: the language forbids it on purpose, so that nobody has to guess the precedence.

```javascript
const result = (a ?? b) && c; // correct
```

Without the parentheses the code does not even parse:

```javascript
SyntaxError: Unexpected token '&&'
```

`??` is often paired with optional chaining, and there parentheses are not needed, because `?.` is not a logical operator:

```javascript
const city = user?.address?.city ?? 'Unknown';
```

### Summary table

| Characteristic | The `??` operator | The `\|\|` operator |
| --- | --- | --- |
| Checks for | only `null` and `undefined` | all falsy values (`0`, `''`, `false`, `NaN`, `null`, `undefined`) |
| Returns | the first non-nullish value | the first truthy value |
| Used for | default values | logical checks |

### Common mistakes
- **Using `||` for numeric defaults.** `count || 10` turns a perfectly valid `0` into `10`. Such cases need `??`.
- **Mixing `??` with `&&` or `||` without parentheses.** This is not a linter warning but a real `SyntaxError` at parse time.
- **Expecting `??` to filter out an empty string.** `'' ?? 'default'` returns `''`. If an empty string must be replaced as well, check it explicitly: `value?.trim() || 'default'`.
- **Confusing `??` with `?.`.** `?.` safely reads a property and yields `undefined`, while `??` substitutes a value. They complement each other rather than replace each other.
- **Thinking `??=` is the same as `=`.** The assignment operator `x ??= 5` writes the value only when `x` is `null` or `undefined`.

Markdown · drag & drop images · ⌘B / ⌘I shortcuts792 words

For the reviewer

Note to the moderator (optional)

Visible only to the moderator. Helps review go faster.