Primitive types

Seven kinds of simple values

A user profile on a shop site holds a few simple values: a name, an age, whether the user is a member. JavaScript calls simple values like these primitives. A primitive is one plain value, like "Asha" or 31, with nothing stored inside it. JavaScript has seven kinds of them (the Data types lesson covers each one), and TypeScript has a type for each kind.

As in the last lesson, you write a type after a name with a colon: age: number means "age must hold a number". That is a type annotation. Here is one value of every kind, each with its type:

1const userName: string = "Asha";2const age: number = 31;3const isMember: boolean = true;4const profileViews: bigint = 9007199254740993n;5const sessionKey: symbol = Symbol("session");6const coupon: null = null;7const nickname: undefined = undefined;8console.log(typeof userName, typeof age, typeof isMember, typeof profileViews);9console.log(typeof sessionKey, typeof coupon, typeof nickname);

Line by line:

• Lines 1 to 3 are the three you'll write most: string for text, number for numbers, and boolean for true or false.
• Line 4 is a bigint, a whole number of any size. The n at the end makes it one.
• Line 5 is a symbol, a unique value made by Symbol().
• Lines 6 and 7 are null and undefined, two ways to say "nothing here". Each one is a type with exactly one value.
• Line 8 prints string number boolean bigint and line 9 prints symbol object undefined. JavaScript's typeof gives back the name of a value's kind (Checking types covers it).

TypeScript reports no errors: every value matches its type. Notice the type names are the same words typeof prints. That's on purpose. There is one exception, null:

Read each row as: this value, what JavaScript's typeof prints for it, and the type you write in TypeScript. typeof null prints "object" because of a mistake in the first version of JavaScript that can't be fixed without breaking old pages. TypeScript gives null its own type, named null.

string, number, and boolean

Most values on a page are text, numbers, or yes-or-no answers. Here is one of each for a product on a shop page:

1let title: string = "Green tea";2let price: number = 3.5;3let inStock: boolean = true;4 5price = 4;6inStock = false;7console.log(title, price, inStock);

Line 1 says title is a string: any text, short or long, in single quotes, double quotes, or backticks (Strings). Line 2 says price is a number. Line 3 says inStock is a boolean: true or false, nothing else (Booleans).

These are let variables, so they can change. Line 5 puts a new price in, and line 6 marks the product sold out. Both new values match their types, so there are no errors. Line 7 prints Green tea 4 false.

Some languages have one type for whole numbers and another for decimals. TypeScript doesn't, because JavaScript doesn't: 3, 3.5, -3, and even NaN are all numbers (Numbers). Try it. Type a discount on line 2 and watch the list under the code:

1const price: number = 20;2const discount: number = 5;3console.log(price - discount);

2.5, -5, and NaN are all numbers, so the errors stay away. "5" in quotes is text, true is a boolean, and 5n is a bigint, so each one gets Type '…' is not assignable to type 'number'. That message means "this kind of value can't be stored where a number has to go". TypeScript checks the kind of value, not whether it's a sensible discount: a negative one is fine.

A type also decides what you can do with a value. Strings have text methods like toUpperCase(), and numbers have number methods like toFixed(), which rounds to a number of decimal places. Mix them up and TypeScript notices:

1const title: string = "Green tea";2const price: number = 3.5;3console.log(title.toUpperCase());4console.log(price.toFixed(2));5console.log(price.toUpperCase());

Line 3 prints GREEN TEA, and line 4 prints 3.50. Line 5 calls toUpperCase() on the price. TypeScript marks it, on purpose here: Property 'toUpperCase' does not exist on type 'number'. In plain words: "a number has no method with that name". When the code runs, line 5 throws a TypeError and stops. The same knowledge drives your editor's suggestions: type price. and it lists only number methods.

null and undefined

JavaScript has two values that mean "nothing here". undefined is what you get when nothing was ever stored, like a variable with no value yet. null is a value you store on purpose to say "empty", like a coupon box the shopper cleared (null and undefined cover both).

In TypeScript, each is its own type, with exactly one value. A string can't hold either of them:

1let coupon: string = "SAVE10";2coupon = null;3 4let nickname: string = undefined;

Line 1 gives coupon the text "SAVE10". Line 2 clears it with null, and TypeScript marks it: Type 'null' is not assignable to type 'string'. Line 4 tries to start nickname as undefined and gets the same error for undefined. Both are on purpose. If they got through, a later coupon.toUpperCase() would throw, because null has no methods.

This check comes from a compiler option called strictNullChecks. It is part of strict, the set of checks most projects turn on, and every example in these lessons uses it. Here is the same code with that one option turned off; the list under the code shows the option:

1let coupon: string = "SAVE10";2coupon = null;3 4let nickname: string = undefined;5console.log(coupon, nickname);

Now null and undefined fit into any type, so there are no errors, and line 5 prints null undefined. That's how TypeScript worked before the option existed. Keep it on: without it, a missing value hides inside a string until the page throws.

The types null and undefined themselves look like this:

1const coupon = null;2//    ^?3const nickname: undefined = undefined;4console.log(typeof coupon, typeof nickname);

The query on line 2 shows TypeScript gives coupon the type null. Line 3 annotates nickname as undefined. Line 4 prints object undefined: the old typeof null mistake again. A name that can only ever hold null isn't much use on its own. You'll mostly use these two types together with another one, as in "a string, or null when the coupon is empty". The Union types and null, undefined & strictNullChecks lessons show how.

Lowercase string, not String

TypeScript also has types called String, Number, and Boolean, with capital letters. They look like the same thing. They aren't. String is the type of a wrapper object: an object made with new String("Pune") that holds the text inside it (Methods of primitives explains wrappers).

1const city: string = "Pune";2const boxedCity: String = new String("Pune");3const copy: string = boxedCity;4console.log(typeof city, typeof boxedCity);

Line 1 is a plain string. Line 2 makes a String object. Line 3 tries to store that object in a string, and TypeScript marks it on purpose with a message in two parts:

• Type 'String' is not assignable to type 'string': the object can't go where plain text has to go.
• 'string' is a primitive, but 'String' is a wrapper object. Prefer using 'string' when possible. TypeScript even tells you which one to write.

Line 4 prints string object: to JavaScript, the wrapper really is an object. The mix-up usually starts the other way round, because TypeScript lets plain text go into a String without complaint:

1const label: String = "Order";2//    ^?3console.log(label.toUpperCase());

Line 1 annotates label with String, and the query on line 2 confirms that is its type. There are no errors, and line 3 prints ORDER. So code with a capital String seems to work, until you pass label to something that needs a string and get the error from the example before. Write the lowercase types every time:

The table below lists both spellings. Read each row as: this type, what it describes, and whether to write it.

bigint and symbol

A number keeps whole numbers exact only up to 9007199254740991. Past that, it rounds. A bigint holds a whole number of any size exactly. You write one with an n at the end (BigInt):

1const numberViews: number = 9007199254740993;2const totalViews: bigint = 9007199254740993n;3console.log(numberViews);4console.log(totalViews + 1n);

Line 1 stores 9007199254740993 in a number. Line 2 stores the same digits in a bigint. Line 3 prints 9007199254740992: the number was rounded to the nearest value it can hold, with no warning. Line 4 adds 1n, another bigint, and prints 9007199254740994n, exactly right.

number and bigint are different types, and JavaScript refuses to mix them in a sum. TypeScript tells you before it runs:

1const totalViews: bigint = 9007199254740993n;2const newViews: number = 1;3console.log(totalViews + newViews);

Line 3 adds newViews, a number, to a bigint. TypeScript marks it on purpose: Operator '+' cannot be applied to types 'bigint' and 'number', which means "+ doesn't work with one of each". When it runs, JavaScript throws TypeError: Cannot mix BigInt and other types. The fix is to turn the number into a bigint first:

1const totalViews: bigint = 9007199254740993n;2const newViews: number = 1;3console.log(totalViews + BigInt(newViews));

Line 3 now wraps newViews in BigInt(…), which gives back 1n. Both sides are bigints, the error is gone, and it prints 9007199254740994n.

The table below compares the two number types. Read each row as a question, then each type's answer.

Bigints arrived in JavaScript in 2020, so TypeScript only accepts the n when your project targets a JavaScript version from 2020 or later. The target option says which version your code must run on. This example sets it to 2019:

1const totalViews: bigint = 9007199254740993n;2console.log(totalViews);

Line 1 gets BigInt literals are not available when targeting lower than ES2020. "BigInt literal" means a number written with an n, and ES2020 is the 2020 version of JavaScript. The browser running this page is newer, so it still prints 9007199254740993n, but an older browser couldn't run it. These lessons target ES2022, so bigints work everywhere else on the page.

The last primitive is symbol. Every call to Symbol() makes a brand-new value that equals no other, even with the same description. Symbols are used as hidden property keys, such as a key a library stores on your objects without clashing with your own names (Symbols).

1const sessionKey = Symbol("session");2//    ^?3let currentKey = Symbol("session");4//  ^?5console.log(sessionKey === currentKey);6console.log(sessionKey.description);

The query on line 4 shows let currentKey: symbol: any symbol may go in it later. The query on line 2 shows something new: const sessionKey: typeof sessionKey. Because a const symbol can never be swapped for another, TypeScript gives it a type of its own, which only this one symbol has. (Its name is unique symbol; you'll rarely write it.) Line 5 prints false, because two calls make two different symbols. Line 6 prints session, the description you passed in.

That type of its own lets TypeScript spot a comparison that can never be true:

1const cartKey = Symbol("cart");2const savedKey = Symbol("cart");3console.log(cartKey === savedKey);

Lines 1 and 2 make two const symbols with the same description. Line 3 compares them, and TypeScript marks it on purpose: This comparison appears to be unintentional because the types 'typeof cartKey' and 'typeof savedKey' have no overlap. In plain words: "these two can never be equal, so you probably meant something else". It runs and prints false.

Typing constants

Most examples so far wrote their types. You don't have to: TypeScript works out a type from the starting value. With a const, the answer can surprise you:

1const minOrder = 50;2//    ^?3let cartTotal = 42;4//  ^?5cartTotal = 58;6console.log(cartTotal >= minOrder);

Line 1 makes minOrder, the cart total that earns free shipping. The query on line 2 says const minOrder: 50. The type is 50, not number. A const can never change, so TypeScript keeps the exact value. 50 is still a number, so it works anywhere a number goes: line 6 compares it and prints true.

Line 3 makes cartTotal with let, and the query on line 4 says number. A let can change, so TypeScript allows any number later, like the 58 on line 5. Types that are one exact value, like 50, have a lesson of their own, Literal types. For now, read const minOrder: 50 as "a number that is always 50".

Each name still only takes what its declaration allows:

1const minOrder = 50;2let cartTotal = 42;3 4minOrder = 60;5cartTotal = "free";

Both errors are on purpose:

• Line 4: Cannot assign to 'minOrder' because it is a constant. "Assign" means "store a new value". A const can't take one, and JavaScript would throw a TypeError here (Variables covers const).
• Line 5: Type 'string' is not assignable to type 'number'. cartTotal started as a number, so its type is number, and the text "free" can't go in.

You can still write a type on a constant. Then TypeScript uses the type you wrote instead of the exact value. Switch line 1 between the three ways to declare minOrder and watch the query on line 2:

1const minOrder = 50;2//    ^?3minOrder = 60;4console.log(minOrder);

const gives 50 and an error on line 3. let gives number and no error. const with : number gives number but keeps the error, because the annotation changes the type, not the fact that it's a constant. Most constants don't need an annotation: const minOrder = 50 already says everything. Write one when you want the wider type, or to make sure the starting value is the kind you meant.

A product card on a shop page

A product card shows a name, a price, a stock badge, and a view count. Here are its values, each with the primitive type it needs, and the text the card shows:

1const title: string = "Green tea";2const price: number = 3.5;3const inStock: boolean = true;4const views: bigint = 9007199254740993n;5 6const label = `${title}: $${price.toFixed(2)}`;7//    ^?8const badge = inStock ? "In stock" : "Sold out";9console.log(label, badge);10console.log(`${views} views`);

Lines 1 to 4 hold the product's values: a string, a number, a boolean, and a bigint, because the view count is past what a number holds exactly. Line 6 builds the label with a template literal, and the query on line 7 shows it's a string. TypeScript allowed price.toFixed(2) because price is a number. Line 8 picks a badge from the boolean. Line 9 prints Green tea: $3.50 In stock, and line 10 prints 9007199254740993 views: inside a template literal, a bigint shows without its n.

Common mix-ups

• "String and string are the same type." No. string is text. String is a wrapper object made with new String(…). Write lowercase.
• "Decimals need a different type from whole numbers." No. 3 and 3.5 are both number. Only very large whole numbers need bigint.
• "NaN isn't a number, so TypeScript rejects it." No. NaN is a value of the number type, and typeof NaN is "number".
• "typeof null is "object", so null's type is an object." No. That's an old JavaScript mistake. TypeScript's type for null is null.
• "null fits in any type." Only with strictNullChecks off. With it on, a string can't hold null or undefined.
• "const minOrder = 50 has the type number." No. Its type is 50, because a const never changes. It still works anywhere a number goes.
• "A bigint and a number can be added like any two numbers." No. TypeScript reports it, and JavaScript throws a TypeError. Convert one with BigInt(…) or Number(…) first.

Practice exercises

Each exercise is TypeScript. When you fix code, press Edit & run on the starter code: the errors update as you type, and the console shows what it prints. Try a guess first, then use the hints.

1let inStock = false;2inStock = true;

1let inStock = false;2//  ^?3inStock = true;

const userName: string = "Asha";
const age: number = 31;
const isMember: boolean = "true";
const city: string = "Pune";

1const userName: string = "Asha";2const age: number = 31;3const isMember: boolean = true;4const city: string = "Pune";

1function greet(name: String): String {2  return "Hi, " + name;3}4const message: string = greet("Asha");5console.log(message);

1function greet(name: string): string {2  return "Hi, " + name;3}4const message: string = greet("Asha");5console.log(message);

1const totalViews: bigint = 9007199254740993n;2const newViews: number = 2;3console.log(totalViews + newViews);

1const totalViews: bigint = 9007199254740993n;2const newViews: number = 2;3console.log(totalViews + BigInt(newViews));

1const maxItems = 10;2let itemsInCart = 3;3itemsInCart = itemsInCart + 1;

1const maxItems = 10;2//    ^?3let itemsInCart = 3;4//  ^?5itemsInCart = itemsInCart + 1;

1const cartKey = Symbol("cart");2const savedKey = Symbol("cart");3console.log(cartKey === savedKey);

1const cartKey = Symbol("cart");2const savedKey = cartKey;3console.log(cartKey === savedKey);

Check your understanding

For each question, keep two things apart: the type TypeScript gives a value, and what JavaScript does with it when the code runs. The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• TypeScript has seven primitive types: string, number, boolean, bigint, symbol, null, and undefined.
• One number type covers whole numbers, decimals, and NaN. A bigint is a whole number of any size, written with n, and doesn't mix with numbers.
• With strictNullChecks on, null and undefined are types of their own and don't fit in a string or number.
• Write lowercase types. String, Number, and Boolean are wrapper objects.
• A const gets its exact value as its type, like 50; a let gets number. An annotation replaces that with the type you wrote.

Coming next: Type annotations & inference. It shows when to write a type yourself and when to let TypeScript work it out.