skip to content

In Zod 4, how does z.enum() validate a TypeScript enum compared with a string array, and what replaced z.nativeEnum()?

level: middleimportance: should knowfreq 40%

answer

  1. one function, two input shapes
  2. values checked, not member names
  3. reverse-mapping keys are skipped
  4. query text is not a number
  5. as const keeps literal types

basics

~20 s

In Zod 4, z.enum() accepts both a string array and an enum-like object, so z.nativeEnum() is deprecated. Either way it checks values, not member names: enum Priority { Low = 1, High = 2 } accepts 1 and 2 but rejects "Low" and the text "1".

solid answer

~40 s

Zod 4 overloaded `z.enum()`: `z.enum(["draft", "published"])` takes strings, and `z.enum(Status)` takes a TypeScript enum or an `as const` object. `z.nativeEnum()` still exists but is deprecated. In both cases Zod builds the set of allowed *values* and checks membership, and a miss raises `invalid_value` listing them. For a string enum with `Active = "active"`, the value `"active"` passes and the member name `"Active"` fails. For a numeric enum Zod skips the reverse-mapping keys TypeScript emits, so only the numbers pass, and the text `"1"` from a query string fails until you convert it to a number first. The schema exposes `.enum` and `.options` plus `.extract()` and `.exclude()`; the old `.Enum` and `.Values` accessors were removed. With an array held in a variable, add `as const`, or the inferred type widens to `string`.

code

typescript · 19 lines
typescript
import * as z from "zod";

enum Priority { Low = 1, High = 2 }
enum Status { Active = "active", Archived = "archived" }

const PrioritySchema = z.enum(Priority);
PrioritySchema.safeParse(1).success;     // true
PrioritySchema.safeParse("Low").success; // false: names are not values
PrioritySchema.safeParse("1").success;   // false: text, not the number 1

const StatusSchema = z.enum(Status);
StatusSchema.safeParse("active").success; // true
StatusSchema.safeParse("Active").success; // false

const Sort = z.enum(["asc", "desc"]);
Sort.options; // ["asc", "desc"]

const PriorityParam = z.coerce.number().pipe(z.enum(Priority));
PriorityParam.safeParse("2").success; // true: converted to 2, then checked

go deeper

for a junior

Recall that z.enum() takes either a string array or an existing enum object, and that it checks the values a client sends, not the member names.

for a middle

Explain how Zod skips numeric reverse-mapping keys, why "1" fails a numeric enum, and what .enum, .options, .extract() and .exclude() give you.

for a senior

Diagnose enum failures at text boundaries: spot the numeric enum fed from a query string and convert the input before the membership check.

for a principal

Weigh where the closed set should live: declaring the array in the schema and deriving the type keeps one source of truth across services.

## One function, two input shapes `z.enum()` is Zod's schema for a **closed set of allowed values**. In Zod 4 it accepts two shapes of input: - **A tuple of strings**, such as `z.enum(["draft", "published", "archived"])`. The inferred type is the union of those strings. - **An enum-like object**, meaning a TypeScript `enum` declared elsewhere or a plain object marked `as const`, such as `z.enum(Status)`. The inferred type is the union of the object's member values, which for a TypeScript enum is the enum type. In Zod 3 the second shape needed a separate function, `z.nativeEnum()`. Zod 4 merged it into `z.enum()`. `z.nativeEnum()` still exists, but its doc comment marks it `@deprecated` and points you to `z.enum()`. The Zod docs also remark that the TypeScript `enum` keyword is not recommended, so a Zod-first codebase often declares the string array and derives the type from the schema. ## Values, not names Whatever shape you pass, Zod builds a set of the **values** and checks that the input is in it, using exact equality. A miss produces an `invalid_value` issue whose `values` field lists what was allowed. Zod 4 merged Zod 3's separate enum and literal issues into this one code. | Declaration | Accepts | Rejects | |---|---|---| | `z.enum(["asc", "desc"])` | `"asc"`, `"desc"` | `"ASC"`, `"ascending"` | | `enum Status { Active = "active" }` | `"active"` | the member name `"Active"` | | `enum Priority { Low = 1, High = 2 }` | `1`, `2` | `"Low"`, `"1"`, `3` | | `{ Draft: 0, Live: 1 } as const` | `0`, `1` | `"Draft"`, `2` | The string-enum row catches people who assume Zod matches member names. A client must send the enum's value, `"active"`, not the identifier in your source code. The same holds for an `as const` object: its keys are labels for your code, and only its values are accepted on the wire. ## Numeric enums and reverse mapping A numeric TypeScript enum compiles to an object that maps both ways: names to numbers and numbers back to names. Zod has to avoid treating those reverse-mapping entries as allowed values, and it does: - When it reads the object, Zod drops every key that is itself one of the numeric values, so the reverse mapping disappears. - What remains is the set of real values, so `z.enum(Priority)` accepts `1` and `2` and rejects the names `"Low"` and `"High"`. - Values are compared by type as well as content, so the string `"1"` is not the number `1`. Why the compiler emits that object at all is TypeScript material; what matters here is that Zod checks values only. ## Numeric enums in a query string The last point bites on a search endpoint. A query string such as `?priority=2` arrives as the text `"2"`, and `z.enum(Priority)` rejects it, because the set holds numbers. The fix is to turn the text into a number before the membership check, for example `z.coerce.number().pipe(z.enum(Priority))`. A string enum avoids the issue entirely, because the query text already has the right type. ## The schema's helpers A Zod 4 enum schema carries a few useful members: - `.enum` returns the value object, for example `{ asc: "asc", desc: "desc" }` for an array schema, or the enum itself for `z.enum(Priority)`. - `.options` returns the allowed values as an array, handy for building a select list or documentation. For a numeric enum it lists only the numbers, because Zod reuses the cleaned value set rather than the raw object. - `.extract([...])` and `.exclude([...])` derive a narrower enum schema from an existing one. - `.Enum` and `.Values`, long-deprecated Zod 3 aliases, were removed in Zod 4; use `.enum`. ## Pitfalls checklist 1. **Widened arrays.** `const sorts = ["asc", "desc"]` is typed `string[]`, so `z.enum(sorts)` infers plain `string`. Pass the array inline or declare it `as const`. 2. **Names versus values.** Send and store the enum's values; member names never pass. 3. **Text versus numbers.** Coerce numeric enum input that arrives as text before checking membership. 4. **Deprecated calls.** Replace `z.nativeEnum(X)` with `z.enum(X)` and `.Enum` or `.Values` with `.enum` when upgrading from Zod 3. Used this way, `z.enum()` gives one membership check for every shape of closed set, and the issue it raises always tells the caller which values were allowed.

  • In Zod 4, why does z.enum(sorts) infer plain string when sorts is an array declared earlier?
    A mutable array literal is typed `string[]`, so TypeScript has already lost the individual values before Zod sees them. Pass the array straight into `z.enum()` or declare it `as const`, which keeps the literal types, and the inferred type becomes the union of the values again.
  • How do you derive a narrower schema from an existing Zod 4 enum, such as statuses a client may set?
    Use `.extract()` to keep listed members or `.exclude()` to drop them: `z.enum(["draft", "live", "archived"]).exclude(["archived"])` yields a new enum schema without that member. Both take keys of the enum object (for an array schema the keys are the values) and return a fresh schema, leaving the original unchanged.

  • z.nativeEnum() is still the way to pass a TypeScript enum in Zod 4
  • z.enum() over a string enum accepts the member names
  • A numeric enum schema accepts the query text "1" as 1
  • z.enum() over a numeric enum also accepts the reverse-mapped names
  • The .Values accessor still lists an enum schema's values in Zod 4

Assumes Zod 4; z.enum() now accepts enum-like objects, z.nativeEnum() is deprecated, and the .Enum and .Values accessors were removed.