How to Handle TS2533: Object Is Possibly 'null' or 'undefined' in TypeScript

By the end of this page, you will understand why TypeScript warns about optional properties, why assignment in one function does not automatically guarantee safety in another, and how to fix TS2533 using proper narrowing, non-null assertions, type assertions, better state design, and helper patterns.

TypeScript shows errors like TS2533: Object is possibly 'null' or 'undefined' when a value might not exist at runtime.

In your example, the property is declared as optional:

listEle?: HTMLElement

An optional property means:

HTMLElement | undefined

So when you write:

$protected.listEle.classList.add('visible');

TypeScript sees a risk: listEle might still be undefined at that moment.

Why TypeScript does this

TypeScript analyzes code based on what is guaranteed by the type system, not what you know happened earlier in another function.

This matters because:

• another function may run before initialization
• another part of the code may reset the property
• control flow across function boundaries is not always guaranteed
• module-level mutable state is harder for TypeScript to prove safe

The real issue

The core issue is not the DOM element itself. The issue is that your type says the property may be missing.

Think of an optional property as a labeled box that may or may not contain an item.

If the label says:

listEle?: HTMLElement

then TypeScript treats it like a box that could be empty.

Before you use the item inside, you must do one of three things:

• look inside the box first with an if check
• declare that you are sure it is there with !
• change your design so the box is always filled before anyone can access it

TypeScript is like a cautious coworker saying:

"I see you want to use listEle, but your type says it might not exist. Prove that it exists, or change the design so that it always does."

1. Narrow with an if check

This is the safest approach.

if ($protected.listEle) {
  $protected.listEle.classList.add('visible');
}

Inside the if block, TypeScript knows listEle is an HTMLElement.

2. Use optional chaining

If you want to do nothing when the value is missing:

$protected.listEle?.classList.add('visible');

This avoids the error and safely skips the call if listEle is undefined.

Use this only when "do nothing if missing" is acceptable.

3. Use the non-null assertion operator !

If you know the value has definitely been assigned before this line:

$protected.listEle!..();

Consider this example:

let state: { listEle?: HTMLElement } = {};

function init() {
  state.listEle = document.createElement('div');
}

function show() {
  state.listEle?.classList.add('visible');
}

What happens step by step

1. Initial state

let state: { listEle?: HTMLElement } = {};

At this point:

• state exists
• state.listEle is undefined

2. Initialization function runs

state.listEle = document.createElement();

DOM elements created later

A component may create DOM nodes during setup and use them later during events.

panelEl?.classList.add('open');

Elements returned from selectors

DOM queries often return null if no match is found.

const button = document.querySelector('button');
button?.addEventListener('click', onClick);

API response fields

A server response may omit optional fields.

type User = {
  name: string;
  avatarUrl?: string;
};

if (user.avatarUrl) {
  console.log(user.avatarUrl);
}

Lazy initialization

Some values are created only when needed.

let : <, > | ;

 () {
   (!cache) cache =  ();
   cache;
}

In real projects, developers usually avoid scattering repeated null checks everywhere by using a few common patterns.

Guard clauses

Exit early if a required value is missing.

function showList() {
  const listEle = $protected.listEle;
  if (!listEle) return;

  listEle.classList.add('visible');
}

This keeps the main logic clean.

Assertion helper functions

Centralize the check in one place.

function requireListEle(): HTMLElement {
  if (!$protected.listEle) {
    throw new Error('listEle is not initialized');
  }
  return $protected.listEle;
}

requireListEle().classList.add('visible');

This is especially useful when missing state is a programmer error.

Separate initialization and ready-state types

Many codebases model state transitions explicitly.

Mistake 1: Assuming assignment in one function guarantees safety everywhere

Broken example:

let state: { listEle?: HTMLElement } = {};

function init() {
  state.listEle = document.createElement('div');
}

function show() {
  state.listEle.classList.add('visible');
}

Why it is a problem:

• show() could run before init()
• the property is still typed as optional

Fix:

function show() {
  state.listEle?.classList.add('visible');
}

or:

function show() {
   listEle = state.;
   (!listEle) ;
  listEle..();
}

// Optional property
listEle?: HTMLElement
// means: HTMLElement | undefined

Safe ways to use possibly undefined values

if ($protected.listEle) {
  $protected.listEle.classList.add('visible');
}

$protected.listEle?.classList.add('visible');

$protected.listEle!.classList.add('visible');

Prefer guard clauses for larger functions

const listEle = $protected.listEle;
if (!listEle) return;

listEle.classList.add('visible');

Use ?? for default values

Why does TypeScript still complain after I assigned the property earlier?

Because the property is still typed as optional, and TypeScript does not assume a mutable shared object stays initialized across different functions.

What is the safest fix for TS2533?

Usually a guard clause or explicit check is the safest fix.

Is the non-null assertion operator ! bad?

Not always. It is fine when you are truly certain a value exists, but it can cause runtime errors if that assumption is wrong.

Should I use optional chaining or an if statement?

Use optional chaining when it is okay to do nothing if the value is missing. Use an if statement when missing values need special handling.

Why is an optional property treated as undefined?

Because prop?: Type means the property may be omitted entirely, so TypeScript models it as Type | undefined.

How can I avoid repeated checks in many places?

Use helper functions, guard clauses, or redesign the state so required values become non-optional after initialization.

Can I just disable strict null checks?

You can, but it removes an important safety feature and usually leads to more runtime bugs. It is better to model the data correctly.

• Optional properties — They are the direct cause of undefined in object types.
• Strict null checks — This TypeScript feature enables errors like TS2533.
• Union types — HTMLElement | undefined is a union type that must be narrowed.
• Type narrowing — if checks let TypeScript reduce a broader type to a safer one.
• Optional chaining — A concise way to safely access values that may be missing.
• Non-null assertion operator — Lets you override TypeScript when you know a value exists.
• Type assertions — Related to telling TypeScript how to treat a value, though different from narrowing.
• Guard clauses — A common real-world pattern for handling missing values early.
• DOM typing in TypeScript — DOM APIs often return nullable values, leading to similar errors.