Skip to main content

Primitive Types

JavaScript has a number of different primitive types (MDN):

ExampleFlow type
Booleanstrue or falseboolean
Strings'foo'string
Numbers123number
Nullnullnull
Undefinedundefinedvoid
Symbols (new in ES2015)Symbol('foo')symbol
BigInts (new in ES2020)123nbigint

Some primitive types appear in the language as literal values:

1true;2"hello";33.14;4null;5undefined;63n;
Try

BigInts and Symbols can be created with calls to BigInt and Symbol, respectively:

1BigInt("2364023476023");2Symbol("hello");
Try

The Flow types of literal values are lowercase (mirroring the output of JavaScript's typeof expression):

1function func(a: number, b: string, c: boolean, d: bigint) { /* ... */ }2
3func(3.14, "hello", true, 3n);
Try

Some literals can also be used as literal types:

1function acceptTwo(x: 2) { /* ... */ }2
3acceptTwo(2); // Works!4acceptTwo(1); // Error!incompatible-typeCannot call acceptTwo with 1 bound to x because 1 [1] is incompatible with 2 [2].
Try

Some primitives can also be wrapped as objects:

NOTE: You probably never want to use the wrapper object variants.

1new Boolean(false);2new String("world");3new Number(42);
Try

Types for the wrapper objects are capitalized (the same as their constructor):

1function func(x: Number, y: String, z: Boolean) {2  // ...3}4
5func(new Number(42), new String("world"), new Boolean(false));
Try

These wrapper objects are rarely used.

Booleans​

Booleans are true and false values in JavaScript. The boolean type in Flow accepts these values.

1function acceptsBoolean(value: boolean) { /* ... */ }2
3acceptsBoolean(true);  // Works!4acceptsBoolean(false); // Works!5
6acceptsBoolean("foo"); // Error!incompatible-typeCannot call acceptsBoolean with "foo" bound to value because "foo" [1] is incompatible with boolean [2].
Try

JavaScript can also implicitly convert other types of values into booleans.

if (42) {} // 42 => true
if ("") {} // "" => false

Flow understands these coercions and will allow them as part of an if statement's test or other conditional contexts.

To explicitly convert non-booleans to a boolean, you can use Boolean(x) or !!x.

1function acceptsBoolean(value: boolean) { /* ... */ }2
3acceptsBoolean(0);          // Error!incompatible-typeCannot call acceptsBoolean with 0 bound to value because 0 [1] is incompatible with boolean [2].4
5acceptsBoolean(Boolean(0)); // Works!6acceptsBoolean(!!0);        // Works!
Try

You can refine a value to boolean using a typeof check:

1function acceptsBoolean(value: boolean) { /* ... */ }2
3function func(value: unknown) {4  if (typeof value === 'boolean') {5    acceptsBoolean(value); // Works: `value` is `boolean`6  }7}
Try

Remember that boolean and Boolean are different types.

  • A boolean is a literal value like true or false or the result of an expression like a === b.
  • A Boolean is a wrapper object created by the global new Boolean(x) constructor. You probably don't want to use this!

Numbers​

Number literals in JavaScript are floating point numbers, for example 42 or 3.14. JavaScript also considers Infinity and NaN to be numbers. These are represented by the number type. JavaScript also has a separate BigInt type.

1function acceptsNumber(value: number) { /* ... */ }2
3acceptsNumber(42);       // Works!4acceptsNumber(3.14);     // Works!5acceptsNumber(NaN);      // Works!6acceptsNumber(Infinity); // Works!7
8acceptsNumber("foo");    // Error!incompatible-typeCannot call acceptsNumber with "foo" bound to value because "foo" [1] is incompatible with number [2].9acceptsNumber(123n);     // Error!incompatible-typeCannot call acceptsNumber with 123n bound to value because 123n [1] is incompatible with number [2].
Try

You can refine a value to number using a typeof check:

1function acceptsNumber(value: number) { /* ... */ }2
3function func(value: unknown) {4  if (typeof value === 'number') {5    acceptsNumber(value); // Works: `value` is `number`6  }7}
Try

Remember that number and Number are different types.

  • A number is a literal value like 42 or 3.14 or the result of an expression like parseFloat(x).
  • A Number is a wrapper object created by the global new Number(x) constructor. You probably don't want to use this!

Strings​

Strings are "foo" values in JavaScript. The string type in Flow accepts these values.

1function acceptsString(value: string) { /* ... */ }2
3acceptsString("foo"); // Works!4acceptsString(`template literal`); // Works!5
6acceptsString(false); // Error!incompatible-typeCannot call acceptsString with false bound to value because false [1] is incompatible with string [2].
Try

JavaScript implicitly converts other types of values into strings by concatenating them.

"foo" + 42; // "foo42"
"foo" + {}; // "foo[object Object]"

Flow will only accept strings and numbers when concatenating them to strings.

1"foo" + "foo"; // Works!2"foo" + 42;    // Works!3`foo ${42}`;   // Works!4
5"foo" + {};    // Error!unsafe-additionCannot use operator + with operands string [1] and object literal [2]6"foo" + [];    // Error!unsafe-additionCannot use operator + with operands string [1] and Array<empty> [2]7`foo ${[]}`;   // Error!incompatible-typeCannot coerce array literal to string because Array<empty> [1] is incompatible with string [2].
Try

You must be explicit and convert other types into strings. You can do this by using the String function or using another method for stringifying values.

1"foo" + String({});     // Works!2"foo" + [].toString();  // Works!3"" + JSON.stringify({}) // Works!
Try

You can refine a value to string using a typeof check:

1function acceptsString(value: string) { /* ... */ }2
3function func(value: unknown) {4  if (typeof value === 'string') {5    acceptsString(value); // Works: `value` is `string`6  }7}
Try

Remember that string and String are different types.

  • A string is a literal value like "foo" or the result of an expression like "" + 42.
  • A String is a wrapper object created by the global new String(x) constructor. You probably don't want to use this!

null and undefined​

JavaScript has both null and undefined. Flow treats these as separate types: null and void (for undefined).

1function acceptsNull(value: null) { /* ... */ }2
3acceptsNull(null);      // Works!4acceptsNull(undefined); // Error!incompatible-typeCannot call acceptsNull with undefined bound to value because void [1] is incompatible with null [2].5
6function acceptsUndefined(value: void) { /* ... */ }7
8acceptsUndefined(undefined); // Works!9acceptsUndefined(null);      // Error!incompatible-typeCannot call acceptsUndefined with null bound to value because null [1] is incompatible with void [2].
Try
TypeScript comparison

Flow has no undefined type — only void. TypeScript's T | undefined corresponds to Flow's T | void. See void vs undefined for the full comparison.

You can refine a value to null or void using equality checks:

1function acceptsNull(value: null) { /* ... */ }2
3function func(value: unknown) {4  if (value === null) {5    acceptsNull(value); // Works: `value` is `null`6  }7}
Try
1function acceptsUndefined(value: void) { /* ... */ }2
3function func(value: unknown) {4  if (value === undefined) {5    acceptsUndefined(value); // Works: `value` is `void`6  }7}
Try

null and void also appear in other types:

Maybe types​

Maybe types are for places where a value is optional and you can create them by adding a question mark in front of the type such as ?string or ?number.

?T is equivalent to T | null | void.

1function acceptsMaybeString(value: ?string) { /* ... */ }2
3acceptsMaybeString("bar");     // Works!4acceptsMaybeString(undefined); // Works!5acceptsMaybeString(null);      // Works!6acceptsMaybeString();          // Works!
Try

To refine, value == null checks exactly for both null and undefined.

Read the maybe type docs for more details.

Optional object properties​

Object types can have optional properties where a question mark ? comes after the property name.

{propertyName?: string}

In addition to their set value type, these optional properties can either be void or omitted altogether. However, they cannot be null.

1function acceptsObject(value: {foo?: string}) { /* ... */ }2
3acceptsObject({foo: "bar"});     // Works!4acceptsObject({foo: undefined}); // Works!5acceptsObject({});               // Works!6
7acceptsObject({foo: null});      // Error!incompatible-typeCannot call acceptsObject with object literal bound to value because in property foo: null [1] is incompatible with string [2].
Try

Optional function parameters​

Functions can have optional parameters where a question mark ? comes after the parameter name.

1function func(param?: string) { /* ... */ }
Try

In addition to their set type, these optional parameters can either be void or omitted altogether. However, they cannot be null.

1function acceptsOptionalString(value?: string) { /* ... */ }2
3acceptsOptionalString("bar");     // Works!4acceptsOptionalString(undefined); // Works!5acceptsOptionalString();          // Works!6
7acceptsOptionalString(null);      // Error!incompatible-typeCannot call acceptsOptionalString with null bound to value because null [1] is incompatible with string [2].
Try

Function parameters with defaults​

Function parameters can also have defaults. This is a feature of ES2015.

1function func(value: string = "default") { /* ... */ }
Try

In addition to their set type, default parameters can also be void or omitted altogether. However, they cannot be null.

1function acceptsOptionalString(value: string = "foo") { /* ... */ }2
3acceptsOptionalString("bar");     // Works!4acceptsOptionalString(undefined); // Works!5acceptsOptionalString();          // Works!6
7acceptsOptionalString(null);      // Error!incompatible-typeCannot call acceptsOptionalString with null bound to value because null [1] is incompatible with string [2].
Try

Symbols​

Symbols are created with Symbol() in JavaScript. The symbol type accepts any symbol. Flow can also track the identity of a specific symbol with a unique symbol type, so you can use it as an object property key.

1function acceptsSymbol(value: symbol) { /* ... */ }2
3acceptsSymbol(Symbol()); // Works!4acceptsSymbol(Symbol.isConcatSpreadable); // Works!5
6acceptsSymbol(false); // Error!incompatible-typeCannot call acceptsSymbol with false bound to value because false [1] is incompatible with symbol [2].
Try

You can refine a value to symbol using a typeof check:

1function acceptsSymbol(value: symbol) { /* ... */ }2
3function func(value: unknown) {4  if (typeof value === 'symbol') {5    acceptsSymbol(value); // Works: `value` is `symbol`6  }7}
Try

Unique symbols ≥0.339​

A unique symbol type stands for one specific symbol. It is a subtype of symbol, and two unique symbols declared separately are different types. Use typeof key to refer to the type of an existing symbol key:

1const inferred = Symbol('inferred');2const annotated: unique symbol = Symbol('annotated');3declare const declared: unique symbol;4
5inferred as symbol; // Works: a unique symbol is a symbol6inferred as typeof inferred; // Works7annotated as typeof inferred; // Error! A different symbolincompatible-typeCannot cast annotated to unique symbol because unique symbol [1] is incompatible with unique symbol [2].8
9function acceptsDeclared(key: typeof declared) { /* ... */ }10acceptsDeclared(declared); // Works11acceptsDeclared(Symbol()); // Error!incompatible-typeCannot call acceptsDeclared with Symbol() bound to key because symbol [1] is incompatible with unique symbol [2].
Try

When you initialize a const directly with a call to Symbol() or Symbol.for(), Flow infers a unique symbol type without an annotation or configuration. A const annotated as symbol and a let or var binding instead have the general symbol type, which does not name a specific property. The same is true of a Symbol() call nested inside an object, an array, or a function result.

1const key = Symbol();2const general: symbol = Symbol();3let rebindable = Symbol();4const holder = {key: Symbol()};5
6const a = {[key]: 1}; // Works7const b = {[general]: 1}; // Error!invalid-computed-propCannot use general [1] to assign a computed property. Computed properties may only be numeric or string literal values, but this one is a symbol [2]. Can you add an appropriate type annotation to general [1]? See for more information on literal types.8const c = {[rebindable]: 1}; // Error!invalid-computed-propCannot use rebindable [1] to assign a computed property. Computed properties may only be numeric or string literal values, but this one is a symbol [2]. Can you add an appropriate type annotation to rebindable [1]? See for more information on literal types.9const d = {[holder.key]: 1}; // Error!invalid-computed-propCannot use holder.key [1] to assign a computed property. Computed properties may only be numeric or string literal values, but this one is a symbol [2]. Can you add an appropriate type annotation to holder.key [1]? See for more information on literal types.
Try

Like an inferred literal type, an inferred unique symbol widens back to symbol when it is stored in a mutable binding or property. An annotated unique symbol does not widen:

1const inferred = Symbol();2const annotated: unique symbol = Symbol();3
4const holder = {inferred, annotated};5holder.inferred = Symbol(); // Works: the property widened to `symbol`6holder.annotated = Symbol(); // Error!incompatible-typeCannot assign Symbol() to holder.annotated because symbol [1] is incompatible with unique symbol [2].
Try

Flow tracks a unique symbol's identity by its declaration, not by runtime equality. Two separate Symbol.for('app') calls return the same runtime symbol but have different types. Conversely, a declaration inside a function or a loop has one type for all the symbols it creates, even if it runs more than once:

1const first = Symbol.for('app');2const second = Symbol.for('app');3second as typeof first; // Error!incompatible-typeCannot cast second to unique symbol because unique symbol [1] is incompatible with unique symbol [2].
Try
TypeScript comparison

As in TypeScript, unique symbol annotations are limited to const declarations, readonly properties, and static readonly class fields. Use typeof key to refer to the type of an existing symbol. Follow the Flow rules described here rather than assuming every TypeScript edge case behaves the same.

Allowed annotation positions​

A bare unique symbol annotation introduces a new symbol identity, so it is only allowed where it describes exactly one value:

  • const declarations, including declare const and exported const declarations
  • readonly properties of object types and interfaces, including optional and computed properties
  • static readonly fields of classes and declare class declarations
1declare const fromLibrary: unique symbol;2export const exported: unique symbol = Symbol();3
4type Registry = {readonly id: unique symbol};5interface Plugin {6  readonly id: unique symbol;7}8class Tokens {9  static readonly key: unique symbol = Symbol();10}11
12let mutable: unique symbol = Symbol(); // Error! Must be `const`unsupported-syntaxA variable whose type is unique symbol must be const. A binding that can be reassigned would let a different symbol take the place of the one this annotation names.13type Writable = {id: unique symbol}; // Error! Must be `readonly`unsupported-syntaxA property whose type is unique symbol must be readonly. A property that can be written would let a different symbol take the place of the one this annotation names.14class Instance {15  readonly key: unique symbol = Symbol(); // Error! Must be `static readonly`unsupported-syntaxA class property whose type is unique symbol must be both static and readonly. An instance property declares one member per instance, and a property that can be written would let a different symbol take the place of the one this annotation names.16}17type Alias = unique symbol; // Error! Use `typeof` an existing symbolunsupported-syntaxunique symbol is only allowed as the type of a const variable, of a readonly property, or of a static readonly class field. Anywhere else one annotation would stand for every value written against it, so distinct symbols would be treated as the same property. Use symbol instead, or typeof a binding declared with unique symbol.18declare function make(): unique symbol; // Error!unsupported-syntaxunique symbol is only allowed as the type of a const variable, of a readonly property, or of a static readonly class field. Anywhere else one annotation would stand for every value written against it, so distinct symbols would be treated as the same property. Use symbol instead, or typeof a binding declared with unique symbol.19declare const list: Array<unique symbol>; // Error!unsupported-syntaxunique symbol is only allowed as the type of a const variable, of a readonly property, or of a static readonly class field. Anywhere else one annotation would stand for every value written against it, so distinct symbols would be treated as the same property. Use symbol instead, or typeof a binding declared with unique symbol.20const registry: Registry = {id: Symbol()}; // Error!incompatible-typeCannot assign object literal to registry because in property id: symbol [1] is incompatible with unique symbol [2].
Try

Flow also rejects unique symbol on var bindings, function parameters, getters, and indexer values. It rejects destructuring patterns, loop bindings, and other nested positions such as unique symbol | string as well.

If an annotated declaration has an initializer, it must be a direct Symbol() or Symbol.for() call. A readonly property annotated with unique symbol describes a symbol held by a declared value. An object literal such as {id: Symbol()} does not create that symbol.

These rules apply to unique symbol as a value type. Using a unique symbol as a property key does not make the property readonly; see symbol-keyed properties.

To reuse a symbol's type in any other position, write typeof key:

1declare const key: unique symbol;2
3type Key = typeof key;4function getKey(): Key {5  return key;6}7function acceptsKey(k: Key) { /* ... */ }8const keys: Array<Key> = [key];
Try

Adoption​

To use unique symbol annotations, set experimental.tslib_syntax=true in .flowconfig and use Flow and flow-parser 0.339.0+ and Prettier 3.10.0+ with its built-in flow parser.

Well-known symbols​

Flow recognizes JavaScript's well-known symbols, such as Symbol.iterator, Symbol.asyncIterator, and Symbol.dispose. You can use them as computed keys in object types, interfaces, and classes. Flow uses these symbols to check language protocols; for example, a [Symbol.iterator]() method makes a type iterable:

1type Countdown = {2  [Symbol.iterator](): Iterator<number>,3};4declare const countdown: Countdown;5for (const n of countdown) {6  n as number; // Works7}8countdown as Iterable<string>; // Error!incompatible-typeCannot cast countdown to Iterable<string> because: in property @@iterator: Iterator<number> [1] is incompatible with Iterator<string, void, void> [2] in the return value > type argument T [3]: number [4] is incompatible with string [5]
Try

Flow's types for these symbols describe the language; they do not polyfill a symbol for a runtime that lacks it.

BigInts​

BigInts can be used to represent integers of arbitrary precision. In other words, they can store integers which are too large to store as a number.

A bigint literal is just a number literal along with an n suffix.

Note that bigint and number are incompatible types. That is, a bigint cannot be used where a number is expected, and vice versa.

1function acceptsBigInt(value: bigint) { /* ... */ }2
3acceptsBigInt(42n); // Works!4acceptsBigInt(42); // Error!incompatible-typeCannot call acceptsBigInt with 42 bound to value because 42 [1] is incompatible with bigint [2].
Try

You can refine a value to bigint using a typeof check:

1function acceptsBigInt(value: bigint) { /* ... */ }2
3function func(value: unknown) {4  if (typeof value === 'bigint') {5    acceptsBigInt(value); // Works: `value` is `bigint`6  }7}
Try

See Also​

  • Literal Types — using specific primitive values (like 2 or "foo") as types
  • Maybe Types — making any type nullable with the ?T shorthand
  • Refinements — narrowing from broad types to specific primitives using typeof