Maybe Types
?T is shorthand for the union T | null | void. It accepts the value, null, or undefined.
1function acceptsMaybeNumber(value: ?number) {2 // ...3}4
5acceptsMaybeNumber(42); // Works!6acceptsMaybeNumber(); // Works! (implicitly undefined)7acceptsMaybeNumber(undefined); // Works!8acceptsMaybeNumber(null); // Works!9acceptsMaybeNumber("42"); // Error!incompatible-typeCannot call acceptsMaybeNumber with "42" bound to value because string [1] is incompatible with number [2].When to use this
Prefer ?T for values that may be absent entirely (optional config, uninitialized state). Use T | null instead when you want to accept null but still require the caller to explicitly pass an argument. For optional object properties, use the key?: T syntax rather than key: ?T — see optional properties.
Maybe types as function parameters
Because ?T includes void, using it as a function parameter type makes the argument implicitly optional — callers can omit it entirely. If you want to require callers to always pass an argument while still accepting null, use T | null instead:
1function acceptsNull(value: number | null) {2 // ...3}4
5acceptsNull(42); // Works!6acceptsNull(null); // Works!7acceptsNull(); // Error! Argument is required.incompatible-typeCannot call acceptsNull because: Either undefined [1] is incompatible with null [2]. Or undefined [1] is incompatible with number [3].In the case of objects, a missing property is not the same thing as an explicitly undefined property.
1function acceptsMaybeProp({value}: {value: ?number}) {2 // ...3}4
5acceptsMaybeProp({value: undefined}); // Works!6acceptsMaybeProp({}); // Error!incompatible-typeCannot call acceptsMaybeProp with object literal bound to the first parameter because property value is missing in object literal [1] but exists in object type [2].If you want to allow missing properties, use the optional property syntax, where the ? is placed before the colon.
It is also possible to combine both syntaxes for an optional maybe type, for example {value?: ?number}.
Refining maybe types
Imagine we have the type ?number, if we want to use that value as a number
we'll need to first check that it is not null or undefined.
1function acceptsMaybeNumber(value: ?number): number {2 if (value !== null && value !== undefined) {3 return value * 2;4 }5 return 0;6}You can simplify the two checks against null and undefined using a single
!= null check which will do both.
1function acceptsMaybeNumber(value: ?number): number {2 if (value != null) {3 return value * 2;4 }5 return 0;6}Most double equal checks are discouraged in JavaScript, but the above pattern is safe (it checks for exactly null and undefined).
You could also flip it around, and check to make sure that the value has a type
of number before using it.
1function acceptsMaybeNumber(value: ?number): number {2 if (typeof value === 'number') {3 return value * 2;4 }5 return 0;6}However, type refinements can be lost. For instance, calling a function after refining the type of an object's property will invalidate this refinement. Consult the refinement invalidations docs for more details, to understand why Flow works this way, and how you can avoid this common pitfall.
See Also
- Unions — the general form:
?Tis shorthand forT | null | void - Refinements — how to narrow maybe types before use
- Primitives —
nullandvoidtypes, and optional parameters