useNullishCoalescing

JavaScript (and super languages)

Caution

This rule is part of the nursery group. This means that it is experimental and the behavior can change at any time.

Note

This rule belongs to the types domain. This means that its activation will activate the Biome Scanner to scan the files of your project, and enable the type inference engine. Read more about it in the documentation page

Summary

• Rule available since: v2.4.5
• Diagnostic Category: lint/nursery/useNullishCoalescing
• This rule has a safe fix.
• The default severity of this rule is information.
• This rule belongs to the following domains:
  • types
• Sources:
  • Inspired from @typescript-eslint/prefer-nullish-coalescing

How to configure

biome.json

{
  "linter": {
    "rules": {
      "nursery": {
        "useNullishCoalescing": "error"
      }
    }
  }
}

Description

Enforce using the nullish coalescing operator (??) instead of logical or (||).

?? only checks for null and undefined, while || checks for any falsy value including 0, '', and false. The rule reports ||, ||=, and ternary patterns (x !== null ? x : y) when type analysis shows the left operand is possibly nullish.

Examples

Invalid

invalid-or.ts

declare const maybeString: string | null;
const value = maybeString || 'default';

/invalid-or.ts:2:27 lint/nursery/useNullishCoalescing ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ℹ Use ?? instead of ||.
  
    1 │ declare const maybeString: string | null;
  > 2 │ const value = maybeString || ‘default’;
      │                           ^^
    3 │ 
  
  ℹ The || operator checks for all falsy values (including 0, ”, and false), while ?? only checks for null and undefined.
  
  ℹ This rule is still being actively worked on, so it may be missing features or have rough edges. Visit https://github.com/biomejs/biome/issues/8043 for more information or to report possible bugs.
  
  ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.
  

invalid-or-undefined.ts

declare const maybeNumber: number | undefined;
const value = maybeNumber || 0;

/invalid-or-undefined.ts:2:27 lint/nursery/useNullishCoalescing ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ℹ Use ?? instead of ||.
  
    1 │ declare const maybeNumber: number | undefined;
  > 2 │ const value = maybeNumber || 0;
      │                           ^^
    3 │ 
  
  ℹ The || operator checks for all falsy values (including 0, ”, and false), while ?? only checks for null and undefined.
  
  ℹ This rule is still being actively worked on, so it may be missing features or have rough edges. Visit https://github.com/biomejs/biome/issues/8043 for more information or to report possible bugs.
  
  ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.
  

invalid-or-assign.ts

declare let x: string | null;
x ||= 'default';

/invalid-or-assign.ts:2:3 lint/nursery/useNullishCoalescing ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ℹ Use ??= instead of ||=.
  
    1 │ declare let x: string | null;
  > 2 │ x ||= ‘default’;
      │   ^^^
    3 │ 
  
  ℹ The ||= operator assigns when the left side is falsy, while ??= only assigns when it is null or undefined.
  
  ℹ This rule is still being actively worked on, so it may be missing features or have rough edges. Visit https://github.com/biomejs/biome/issues/8043 for more information or to report possible bugs.
  
  ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.
  

declare const x: string | null;
const value = x !== null ? x : 'default';

code-block.ts:2:15 lint/nursery/useNullishCoalescing  FIXABLE  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ℹ Prefer ?? over a ternary expression checking for nullish.
  
    1 │ declare const x: string | null;
  > 2 │ const value = x !== null ? x : ‘default’;
      │               ^^^^^^^^^^
    3 │ 
  
  ℹ This rule is still being actively worked on, so it may be missing features or have rough edges. Visit https://github.com/biomejs/biome/issues/8043 for more information or to report possible bugs.
  
  ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.
  
  ℹ Safe fix: Replace the ternary with ??.
  
    1 1 │   declare const x: string | null;
    2   │ - const·value·=·x·!==·null·?·x·:·‘default’;
      2 │ + const·value·=·x·??·‘default’;
    3 3 │   
  

declare const x: string | null;
const value = x == null ? 'default' : x;

code-block.ts:2:15 lint/nursery/useNullishCoalescing  FIXABLE  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ℹ Prefer ?? over a ternary expression checking for nullish.
  
    1 │ declare const x: string | null;
  > 2 │ const value = x == null ? ‘default’ : x;
      │               ^^^^^^^^^
    3 │ 
  
  ℹ This rule is still being actively worked on, so it may be missing features or have rough edges. Visit https://github.com/biomejs/biome/issues/8043 for more information or to report possible bugs.
  
  ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.
  
  ℹ Safe fix: Replace the ternary with ??.
  
    1 1 │   declare const x: string | null;
    2   │ - const·value·=·x·==·null·?·‘default’·:·x;
      2 │ + const·value·=·x·??·‘default’;
    3 3 │   
  

Valid

declare const maybeString: string | null;
const value = maybeString ?? 'default';

declare const definiteString: string;
const value = definiteString || 'fallback';

declare const cond: string | null;
if (cond || 'fallback') {
  console.log('in if');
}

declare let y: string | null;
y ??= 'default';

Options

ignoreConditionalTests

Ignore || expressions inside conditional test positions (if/while/for/do-while/ternary). Default: true.

biome.json

{
  "linter": {
    "rules": {
      "nursery": {
        "useNullishCoalescing": {
          "level": "on",
          "options": {
            "ignoreConditionalTests": false
          }
        }
      }
    }
  }
}

declare const cond: string | null;
if (cond || 'fallback') {}

ignoreTernaryTests

Ignore ternary expressions that check for null or undefined. Default: false.

biome.json

{
  "linter": {
    "rules": {
      "nursery": {
        "useNullishCoalescing": {
          "level": "on",
          "options": {
            "ignoreTernaryTests": true
          }
        }
      }
    }
  }
}

declare const x: string | null;
const value = x !== null ? x : 'default';

ignoreMixedLogicalExpressions

Ignore || and ||= whose connected logical tree also contains a &&. Default: false.

biome.json

{
  "linter": {
    "rules": {
      "nursery": {
        "useNullishCoalescing": {
          "level": "on",
          "options": {
            "ignoreMixedLogicalExpressions": true
          }
        }
      }
    }
  }
}

Invalid

|| and ||= are still reported when the surrounding logical tree does not contain &&.

invalid-mixed-or.ts

declare const maybeString: string | null;
const value = maybeString || 'default';

/invalid-mixed-or.ts:2:27 lint/nursery/useNullishCoalescing ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ℹ Use ?? instead of ||.
  
    1 │ declare const maybeString: string | null;
  > 2 │ const value = maybeString || ‘default’;
      │                           ^^
    3 │ 
  
  ℹ The || operator checks for all falsy values (including 0, ”, and false), while ?? only checks for null and undefined.
  
  ℹ This rule is still being actively worked on, so it may be missing features or have rough edges. Visit https://github.com/biomejs/biome/issues/8043 for more information or to report possible bugs.
  
  ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.
  

invalid-mixed-or-assign.ts

declare let assigned: string | null;
assigned ||= 'default';

/invalid-mixed-or-assign.ts:2:10 lint/nursery/useNullishCoalescing ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ℹ Use ??= instead of ||=.
  
    1 │ declare let assigned: string | null;
  > 2 │ assigned ||= ‘default’;
      │          ^^^
    3 │ 
  
  ℹ The ||= operator assigns when the left side is falsy, while ??= only assigns when it is null or undefined.
  
  ℹ This rule is still being actively worked on, so it may be missing features or have rough edges. Visit https://github.com/biomejs/biome/issues/8043 for more information or to report possible bugs.
  
  ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.
  

Valid

|| and ||= mixed with && in the same logical tree are not reported.

declare const a: string | null;
declare const b: string;
const r = (a || 'default') && b;

declare const b: string;
declare let assigned: string | null;
assigned ||= b && 'fallback';

ignoreBooleanCoercion

Ignore || and ||= used inside a Boolean() call, where coalescing on falsy values is intentional. Default: false.

biome.json

{
  "linter": {
    "rules": {
      "nursery": {
        "useNullishCoalescing": {
          "level": "on",
          "options": {
            "ignoreBooleanCoercion": true
          }
        }
      }
    }
  }
}

Invalid

|| and ||= outside a Boolean() call are still reported.

invalid-boolean-coercion.ts

declare const maybeString: string | null;
const value = maybeString || 'default';

/invalid-boolean-coercion.ts:2:27 lint/nursery/useNullishCoalescing ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ℹ Use ?? instead of ||.
  
    1 │ declare const maybeString: string | null;
  > 2 │ const value = maybeString || ‘default’;
      │                           ^^
    3 │ 
  
  ℹ The || operator checks for all falsy values (including 0, ”, and false), while ?? only checks for null and undefined.
  
  ℹ This rule is still being actively worked on, so it may be missing features or have rough edges. Visit https://github.com/biomejs/biome/issues/8043 for more information or to report possible bugs.
  
  ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.
  

Valid

|| and ||= inside a Boolean() call are not reported.

valid-boolean-coercion.ts

declare const a: string | null;
declare const b: string;
const r = Boolean(a || b);

ignorePrimitives

Ignore ||, ||=, and ternary expressions when every non-nullish variant of the operand is a primitive the option opts out of. Use true to ignore all primitives, or an object selecting string, number, boolean, or bigint. Default: none.

biome.json

{
  "linter": {
    "rules": {
      "nursery": {
        "useNullishCoalescing": {
          "level": "on",
          "options": {
            "ignorePrimitives": {
              "string": true
            }
          }
        }
      }
    }
  }
}

Invalid

Primitive kinds that are not opted out of are still reported.

invalid-primitives.ts

declare const count: number | null;
const value = count || 0;

/invalid-primitives.ts:2:21 lint/nursery/useNullishCoalescing ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ℹ Use ?? instead of ||.
  
    1 │ declare const count: number | null;
  > 2 │ const value = count || 0;
      │                     ^^
    3 │ 
  
  ℹ The || operator checks for all falsy values (including 0, ”, and false), while ?? only checks for null and undefined.
  
  ℹ This rule is still being actively worked on, so it may be missing features or have rough edges. Visit https://github.com/biomejs/biome/issues/8043 for more information or to report possible bugs.
  
  ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.
  

Valid

A string operand is not reported when string is ignored.

valid-primitives.ts

declare const name: string | null;
const value = name || 'default';

Related links

• Disable a rule
• Configure the code fix
• Rule options
• Source Code (Edit this Page)
• Test Cases