Enums

Names for a fixed set of choices

An order on a shop page is pending, shipped, or delivered. Many apps store that as a number, because numbers are small and quick to compare. Here is what that looks like in plain JavaScript:

const order = { id: 7, status: 1 };

if (order.status === 1) {
  console.log("Your order is on its way");
}

Line 1 makes order 7 with a status of 1. Line 3 checks whether the status is 1, and line 4 prints Your order is on its way. It works, but what does 1 mean? You have to remember, or find a comment somewhere, that 1 means "shipped". Type a 2 by mistake and nothing tells you.

TypeScript has a feature for this, called an enum (short for "enumeration", a list of every option). An enum gives names to a fixed set of values. Each name in it is a member:

1enum OrderStatus {2  Pending,3  Shipped,4  Delivered,5}6 7const order = { id: 7, status: OrderStatus.Shipped };8 9if (order.status === OrderStatus.Shipped) {10  console.log("Your order is on its way");11}12console.log(order.status);

Lines 1 to 5 make an enum called OrderStatus with three members: Pending, Shipped, and Delivered. You read a member like a property, with a dot: line 7 gives the order the status OrderStatus.Shipped, and line 9 compares with it. Line 10 prints Your order is on its way.

Line 12 shows what the status really is: it prints 1. You didn't write any numbers. TypeScript numbered the members for you, counting from 0, so Pending is 0, Shipped is 1, and Delivered is 2. Your code reads like words, and still stores the small number.

An enum is also a type. status: OrderStatus means "one of the three statuses". Try it: type a value for line 7 and watch the list under the code.

1enum OrderStatus {2  Pending,3  Shipped,4  Delivered,5}6 7const status: OrderStatus = OrderStatus.Shipped;8console.log(status);

OrderStatus.Delivered fits and prints 2. A typo like OrderStatus.Shiped gets an error that suggests the right name. The text "Shipped" gets an error, because a name in quotes isn't the member. The surprise is 1: no error, because some member has the value 1. 7 gets an error, because no member does.

Numeric and string enums

An enum whose members are numbers is a numeric enum. If you give the first member a number, the rest count up from there:

1enum Priority {2  Low = 1,3  Medium,4  High,5}6 7let level = Priority.Medium;8//  ^?9console.log(level, Priority.High);

Line 2 says Low = 1. Lines 3 and 4 have no number, so Medium is 2 and High is 3. Line 7 stores the medium priority, and the query on line 8 shows let level: Priority: the variable can hold any of the three. Line 9 prints 2 3.

You saw that a numeric enum accepts the number 1. It goes further than that, and this is the weak spot of numeric enums:

1enum Priority {2  Low = 1,3  Medium,4  High,5}6 7const typed: Priority = 2;8const tooBig: Priority = 7;9 10const fromServer: number = 7;11const loose: Priority = fromServer;12console.log(typed, tooBig, loose);

Line 7 stores the number 2, which is Medium's value, so it's fine. Line 8 stores 7, and TypeScript marks it on purpose: Type '7' is not assignable to type 'Priority', "no member has the value 7". But line 10 makes a plain number, the way a value from a server would arrive, and line 11 stores it with no error. TypeScript checks a number you write in the code; any value whose type is just number gets in. Line 12 prints 2 7 7.

The other kind is a string enum. Each member gets a text value, written with =. There's no counting, so you write every value:

1enum Theme {2  Light = "light",3  Dark = "dark",4}5 6function setTheme(theme: Theme) {7  console.log(`Switched to ${theme}`);8}9 10setTheme(Theme.Dark);11setTheme("dark");

Lines 1 to 4 make Theme, whose Light member is the text "light" and Dark member is "dark". Line 6 says setTheme takes a Theme. Line 10 passes Theme.Dark, which fits. Line 11 passes the text "dark", and TypeScript marks it on purpose: Argument of type '"dark"' is not assignable to parameter of type 'Theme'. The value is the same, but a string enum accepts only its members. Run it anyway, and both lines print Switched to dark.

String values are easier to read: a log or a saved setting says dark, not 1. The table below compares the two kinds. Read each row as a question, then the answer for each kind.

What an enum compiles to

Most of TypeScript is types, and types are removed before the code runs. An enum is different: your code reads OrderStatus.Shipped while it runs, so something called OrderStatus has to exist. Here is a small enum:

1enum OrderStatus {2  Pending,3  Shipped,4  Delivered,5}6 7console.log(OrderStatus.Shipped);8console.log(OrderStatus[1]);

Line 7 reads a member by name and prints 1. Line 8 reads with a number in square brackets and prints Shipped. That second read only works because of the JavaScript the TypeScript compiler, tsc, writes for the enum:

var OrderStatus;
(function (OrderStatus) {
    OrderStatus[OrderStatus["Pending"] = 0] = "Pending";
    OrderStatus[OrderStatus["Shipped"] = 1] = "Shipped";
    OrderStatus[OrderStatus["Delivered"] = 2] = "Delivered";
})(OrderStatus || (OrderStatus = {}));
console.log(OrderStatus.Shipped);
console.log(OrderStatus[1]);

In plain words, line by line:

1. Line 1 makes a variable, OrderStatus, with no value yet.
2. Lines 2 to 6 are a function that runs as soon as it's made. Line 6 calls it, with OrderStatus || (OrderStatus = {}): if the variable is empty, it first gets a new empty object (the Logical operators lesson covers ||).
3. Line 3 does two stores in one. The inner part, OrderStatus["Pending"] = 0, stores the number 0 under the name Pending. An assignment gives back the value it stored, 0, so the outer part becomes OrderStatus[0] = "Pending": the name stored under the number.
4. Lines 4 and 5 do the same for Shipped (1) and Delivered (2).
5. Lines 7 and 8 are your two reads, unchanged.

Step through it and watch the object fill up:

1var OrderStatus;Run2(function (OrderStatus) {3    OrderStatus[OrderStatus["Pending"] = 0] = "Pending";4    OrderStatus[OrderStatus["Shipped"] = 1] = "Shipped";5    OrderStatus[OrderStatus["Delivered"] = 2] = "Delivered";6})(OrderStatus || (OrderStatus = {}));7console.log(OrderStatus.Shipped);8console.log(OrderStatus[1]);

Each member leaves two entries: one from the name to the number, and one from the number back to the name. The second kind is called a reverse mapping. It's why OrderStatus[1] gives "Shipped", which helps when a number arrives and you want to show its name.

The reverse mapping has a side effect. The object has six keys, not three:

1enum OrderStatus {2  Pending,3  Shipped,4  Delivered,5}6 7console.log(Object.keys(OrderStatus).join(", "));8console.log(Object.keys(OrderStatus).length);

Line 7 lists the object's keys with Object.keys and prints 0, 1, 2, Pending, Shipped, Delivered. Line 8 prints 6. If you build a menu from a numeric enum's keys, you'll get the numbers too. String enums don't have this problem:

1enum Theme {2  Light = "light",3  Dark = "dark",4}5 6console.log(Theme.Dark);

var Theme;
(function (Theme) {
    Theme["Light"] = "light";
    Theme["Dark"] = "dark";
})(Theme || (Theme = {}));
console.log(Theme.Dark);

Lines 3 and 4 store only the name to the text, like Theme["Dark"] = "dark". A string enum has no reverse mapping, so Object.keys(Theme) lists just Light and Dark. Line 6 prints dark.

const enums leave no object

Write const before enum and you get a const enum. It works the same in your code, but tsc doesn't write an object for it. Instead it copies each member's value to every place that uses it:

1const enum Size {2  Small = "S",3  Large = "L",4}5 6const pick = Size.Large;7console.log(pick);

const pick = "L" /* Size.Large */;
console.log(pick);

In the TypeScript, lines 1 to 4 make Size, and line 6 reads Size.Large. In the JavaScript, there's no Size at all. Line 1 holds the value "L" itself, with a comment saying which member it came from. This is called inlining. Line 2 prints L.

Because there's no object, you can only read members of a const enum, never use the enum itself as a value:

1const enum Size {2  Small = "S",3  Large = "L",4}5 6console.log(Object.values(Size).join(", "));

Line 6 passes Size to Object.values, and TypeScript marks it on purpose: 'const' enums can only be used in property or index access expressions …. In plain words: you may write Size.Large or Size["Large"], and nothing else, because there will be no Size to pass.

One more thing to know. Inlining needs the type checker, because tsc must know each member's value. Many build tools turn TypeScript into JavaScript one file at a time, without checking types, and so does this page's editor. They keep a const enum as an ordinary object instead. Your code works the same either way, but don't count on the object being gone.

Literal unions instead

Many teams don't use enums at all. A union of exact texts does most of the same job, with no JavaScript left over. Each option is a literal type: a type that allows one exact value. Here is a search page's sort menu:

1type SortOrder = "relevance" | "price-low" | "price-high";2 3function sortLabel(order: SortOrder) {4  return `Sorted by ${order}`;5}6 7console.log(sortLabel("price-low"));8console.log(sortLabel("cheapest"));

Line 1 says a SortOrder is one of three exact texts. Line 3 says sortLabel takes one. Line 7 passes "price-low", which fits, and prints Sorted by price-low. Line 8 passes "cheapest", which isn't an option, and TypeScript marks it on purpose: Argument of type '"cheapest"' is not assignable to parameter of type 'SortOrder'. So you get the same safety as an enum: only the listed options fit, and the editor suggests them when you type a quote.

What you don't get is names like SortOrder.PriceLow. If you want them, write a plain object with as const, which keeps every value exact and read-only:

1const SortOrder = {2  Relevance: "relevance",3  PriceLow: "price-low",4  PriceHigh: "price-high",5} as const;6 7type SortOrder = (typeof SortOrder)[keyof typeof SortOrder];8//   ^?9 10function sortLabel(order: SortOrder) {11  return `Sorted by ${order}`;12}13 14console.log(sortLabel(SortOrder.PriceLow));15console.log(sortLabel("price-high"));

Lines 1 to 5 are an ordinary JavaScript object with three names and three texts. Line 7 makes the type, and reads from the inside out:

• typeof SortOrder is the type of the object on line 1.
• keyof typeof SortOrder is its names: "Relevance" | "PriceLow" | "PriceHigh".
• The square brackets look up the values at those names, which gives the union of the three texts.

The query on line 8 shows the result: type SortOrder = "relevance" | "price-low" | "price-high". The object and the type can share the name SortOrder, because one is a value and the other is a type. Line 14 uses a name, line 15 uses plain text, and both fit. They print Sorted by price-low and Sorted by price-high. (The keyof & typeof lesson explains line 7 in full.)

Compare the three ways side by side. Each button shows the same sort menu:

1enum SortOrder {2  Relevance = "relevance",3  PriceLow = "price-low",4  PriceHigh = "price-high",5}6 7function sortLabel(order: SortOrder) {8  return `Sorted by ${order}`;9}10 11console.log(sortLabel(SortOrder.PriceLow));12console.log(sortLabel("price-high"));

All three print the same thing. They differ in two places: whether plain text like "price-high" fits, and what tsc leaves in the JavaScript.

That last difference matters more than it used to. Node.js can now run a .ts file by only removing its types, and some build tools work the same way. An enum can't run there, because it's code that has to be written, not a type that can be removed. TypeScript 5.8 added a setting, erasableSyntaxOnly, that reports anything like this:

1enum Theme {2  Light = "light",3  Dark = "dark",4}5 6type ThemeName = "light" | "dark";7const saved: ThemeName = "dark";8console.log(Theme.Dark, saved);

The list under the code shows the setting this example turns on. Line 1 gets This syntax is not allowed when 'erasableSyntaxOnly' is enabled, on purpose. Line 6, a literal union, is only a type, so it's fine. Line 8 prints dark dark.

The table below sums up the choice. Read each row as a question, then the answer for each way.

A simple rule: reach for a literal union first, and an as const object when you also want names or a list of the options. Use an enum when your project already does, or when you want a numeric code with readable names, and know that it becomes an object.

A status badge from a server reply

An order page gets the order's status from a server, as text, and shows a badge for it. A string enum fits well here: its values match the server's text, and the code reads OrderStatus.Shipped. The careful part is turning the server's text into an OrderStatus:

1enum OrderStatus {2  Pending = "pending",3  Shipped = "shipped",4  Delivered = "delivered",5}6 7function badge(status: OrderStatus) {8  switch (status) {9    case OrderStatus.Pending:10      return "Waiting to ship";11    case OrderStatus.Shipped:12      return "On its way";13    case OrderStatus.Delivered:14      return "Delivered";15  }16}17 18function toStatus(text: string) {19  return Object.values(OrderStatus).find((status) => status === text);20}21 22const reply = JSON.parse('{ "id": 7, "status": "shipped" }');23const status = toStatus(reply.status);24//    ^?25console.log(status ? badge(status) : "Unknown status");26console.log(toStatus("lost") ?? "Unknown status");

Lines 1 to 5 make the enum, with the same texts the server sends. Lines 7 to 16 choose the badge text with a switch, one case per member. Lines 18 to 20 turn text into a status: Object.values(OrderStatus) lists the three texts, and find gives back the one that matches, or undefined if none does.

Line 22 reads the server's reply with JSON.parse. Line 23 turns its status into an OrderStatus, and the query on line 24 shows const status: OrderStatus | undefined: TypeScript knows the text might not match. Line 25 checks before it calls badge, and prints On its way. Line 26 tries the text "lost" and prints Unknown status.

Why not pass reply.status straight to badge? JSON.parse gives back any, the type TypeScript doesn't check (see any, unknown & never), so it would let anything through, even "lost". Checking the text against the enum's values first means badge only ever gets a real status.

Common mix-ups

• "An enum is only a type, like a type alias." No. tsc writes an object for it, and your code reads that object while it runs. Only a const enum is removed, and only when tsc compiles it.
• "A numeric enum only accepts its members." No. A number you write is checked, but any value of type number gets in, so Priority can end up holding 7.
• "A string enum accepts its text." No. "dark" doesn't fit a Theme, even though Theme.Dark is "dark". A literal union accepts it.
• "Object.keys gives an enum's names." Only for a string enum. A numeric enum also lists its numbers, because of the reverse mapping.
• "Members are numbered from 1." No. They start at 0, unless you give the first one a number.
• "An enum checks the server's text for me." No. Like every type, it can't see data that arrives while the page runs. Compare the text with Object.values, as the badge code does.

Practice exercises

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

1enum Step {2  Cart,3  Address,4  Payment,5  Done,6}7 8console.log(Step.Payment);

1enum Step {2  Cart, // 03  Address, // 14  Payment, // 25  Done, // 36}7 8console.log(Step.Payment);

enum Theme {
  Light = "light",
  Dark = "dark",
}

const saved: Theme = Theme.Light;
const chosen: Theme = "dark";

1enum Theme {2  Light = "light",3  Dark = "dark",4}5 6const saved: Theme = Theme.Light;7const chosen: Theme = Theme.Dark; // line 7 needed the member, not the text

1enum Priority {2  Low,3  Medium,4  High,5}6 7console.log(Priority.High);

1enum Priority {2  Low = 1,3  Medium,4  High,5}6 7console.log(Priority.High);

1enum OrderStatus {2  Pending,3  Shipped,4  Delivered,5}6 7const fromServer = 2;8console.log(OrderStatus[fromServer]);

1enum OrderStatus {2  Pending, // 03  Shipped, // 14  Delivered, // 25}6 7const fromServer = 2;8console.log(OrderStatus[fromServer]); // the name stored for 2

1enum Theme {2  Light = "light",3  Dark = "dark",4}5 6function setTheme(theme: Theme) {7  console.log(`Switched to ${theme}`);8}9 10setTheme(Theme.Dark);

1type Theme = "light" | "dark";2 3function setTheme(theme: Theme) {4  console.log(`Switched to ${theme}`);5}6 7setTheme("dark");

1enum OrderStatus {2  Pending = "pending",3  Shipped = "shipped",4}5 6function badge(status: OrderStatus) {7  return status === OrderStatus.Shipped ? "On its way" : "Waiting";8}9 10const reply = JSON.parse('{ "status": "shipped" }');11const text: string = reply.status;12console.log(badge(text));

1enum OrderStatus {2  Pending = "pending",3  Shipped = "shipped",4}5 6function badge(status: OrderStatus) {7  return status === OrderStatus.Shipped ? "On its way" : "Waiting";8}9 10const reply = JSON.parse('{ "status": "shipped" }');11const text: string = reply.status;12const status = Object.values(OrderStatus).find((value) => value === text);13console.log(status ? badge(status) : "Unknown status");

Check your understanding

For each question, ask two things: what values the enum has, and what tsc writes for it. The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• An enum gives names to a fixed set of values: OrderStatus.Shipped instead of a bare 1.
• Numeric enums count up from 0, or from the first number you give. String enums give every member its text.
• A numeric enum accepts any number from a variable; a string enum accepts only its members, not their text.
• tsc turns an enum into an object. A numeric enum also maps numbers back to names, so Object.keys lists both.
• A const enum is inlined by tsc and leaves no object, so you can only read its members.
• A literal union, or an as const object, does the same job with no extra code and runs where types are only removed.

Coming next: Typing functions. It shows how to type a function's parameters and the value it gives back, like the badge function on this page.