.nullable() and .nullish()

Make schemas accept null values

.nullable()

Makes a schema accept null in addition to its base type.

import { z } from 'zod';

const schema = z.string().nullable();

schema.parse('hello');     // 'hello'
schema.parse(null);        // null
schema.parse(undefined);   // throws error

Type Inference

The .nullable() modifier affects both input and output types:

const schema = z.string().nullable();

type Input = z.input<typeof schema>;   // string | null
type Output = z.output<typeof schema>; // string | null

Unwrapping

You can remove the nullable wrapper using .unwrap():

const nullable = z.string().nullable();
const base = nullable.unwrap(); // ZodString

In Object Schemas

const User = z.object({
  name: z.string(),
  middleName: z.string().nullable(),
});

User.parse({
  name: 'John',
  middleName: null,        // Valid
});

User.parse({
  name: 'John',
  middleName: 'Robert',    // Valid
});

User.parse({
  name: 'John',
  // middleName is required, cannot be omitted
}); // throws error

.nullable() does not make a field optional in objects. The field must still be present, but can be null.

.nullish()

A convenience method that combines .optional() and .nullable(), making a schema accept null, undefined, or the base type.

const schema = z.string().nullish();

// Equivalent to:
const equivalent = z.string().nullable().optional();

schema.parse('hello');     // 'hello'
schema.parse(null);        // null
schema.parse(undefined);   // undefined

Type Inference

const schema = z.string().nullish();

type Input = z.input<typeof schema>;   // string | null | undefined
type Output = z.output<typeof schema>; // string | null | undefined

In Object Schemas

const User = z.object({
  name: z.string(),
  nickname: z.string().nullish(),
});

User.parse({ name: 'John' });                       // Valid - nickname omitted
User.parse({ name: 'John', nickname: undefined });  // Valid
User.parse({ name: 'John', nickname: null });       // Valid
User.parse({ name: 'John', nickname: 'Johnny' });   // Valid

Use Cases

• .nullable(): Use for database fields that can be NULL but must be present
• .nullish(): Use for optional fields that could also be explicitly set to null

Chaining Examples

// Nullable with default
const schema1 = z.string().nullable().default('hello');
schema1.parse(undefined); // 'hello'
schema1.parse(null);      // null (default not applied to null)

// Nullable with catch
const schema2 = z.string().nullable().catch('fallback');
schema2.parse(123);       // 'fallback' (invalid input)
schema2.parse(null);      // null (valid input)

// Nullish with refinement
const schema3 = z.string()
  .nullish()
  .refine(val => val !== null, 'Cannot be null');

schema3.parse(undefined);  // undefined (valid)
schema3.parse('hello');    // 'hello' (valid)
schema3.parse(null);       // throws error

Implementation Note

// .nullish() is implemented as:
.nullish() {
  return this.nullable().optional();
}

// This means it creates a nested structure:
z.string().nullish()
// Is equivalent to:
z.optional(z.nullable(z.string()))