Использование default значений

Метод default() позволяет задавать значения по умолчанию для схем валидации. Эти значения используются в случаях, когда входное значение отсутствует (undefined) или когда выполняется создание объекта через методы cast() и getDefault().

Базовый синтаксис:

import * as yup from 'yup';

const schema = yup.string().default('guest');

Если значение не передано:

schema.cast(undefined); // 'guest'

Если значение существует, значение по умолчанию не применяется:

schema.cast('admin'); // 'admin'

Поведение default() и undefined

default() срабатывает только для undefined.

const schema = yup.string().default('anonymous');

schema.cast(undefined); // 'anonymous'
schema.cast(null);      // null
schema.cast('');        // ''

Это важный момент:

  • undefined → используется default
  • null → считается реальным значением
  • пустая строка → также считается значением

Значения по умолчанию для строк

const userSchema = yup.object({
  name: yup.string().default('Unknown'),
  role: yup.string().default('user'),
});

Результат:

userSchema.cast({});
{
  name: 'Unknown',
  role: 'user'
}

Значения по умолчанию для чисел

const schema = yup.number().default(0);

schema.cast(undefined); // 0

Совместно с ограничениями:

const ageSchema = yup
  .number()
  .min(18)
  .default(18);

Значения по умолчанию для boolean

const schema = yup.boolean().default(false);

schema.cast(undefined); // false

Практический пример:

const settingsSchema = yup.object({
  darkMode: yup.boolean().default(true),
  notifications: yup.boolean().default(false),
});

Значения по умолчанию для массивов

const schema = yup.array().default([]);

Пример:

schema.cast(undefined); // []

С типизацией элементов:

const tagsSchema = yup
  .array()
  .of(yup.string())
  .default([]);

Значения по умолчанию для объектов

const schema = yup.object({
  city: yup.string().default('Unknown'),
  country: yup.string().default('Kazakhstan'),
});
schema.cast({});

Результат:

{
  city: 'Unknown',
  country: 'Kazakhstan'
}

Использование default() с вложенными объектами

const profileSchema = yup.object({
  user: yup.object({
    name: yup.string().default('Guest'),
    age: yup.number().default(18),
  }),
});
profileSchema.cast({});

Результат:

{
  user: {
    name: 'Guest',
    age: 18
  }
}

Метод getDefault()

Метод getDefault() возвращает значение по умолчанию, определённое в схеме.

const schema = yup.string().default('test');

schema.getDefault(); // 'test'

Для объектов:

const schema = yup.object({
  name: yup.string().default('Anonymous'),
  age: yup.number().default(20),
});

schema.getDefault();

Результат:

{
  name: 'Anonymous',
  age: 20
}

Динамические default-значения

default() может принимать функцию.

Это особенно полезно для:

  • дат;
  • UUID;
  • случайных значений;
  • временных меток.

Пример:

const schema = yup.date().default(() => new Date());

Каждый вызов создаёт новую дату:

schema.getDefault();
schema.getDefault();

Значения будут различаться.

Генерация уникальных идентификаторов

import { v4 as uuid } from 'uuid';

const schema = yup.string().default(() => uuid());

Использование default() с cast()

Метод cast() преобразует данные в соответствии со схемой и подставляет default-значения.

const schema = yup.object({
  name: yup.string().default('No Name'),
  age: yup.number().default(0),
});

schema.cast({});

Результат:

{
  name: 'No Name',
  age: 0
}

Отличие cast() от validate()

cast()

  • преобразует данные;
  • применяет default();
  • не выбрасывает ошибки валидации.
schema.cast({});

validate()

  • проверяет данные;
  • может использовать default;
  • выбрасывает ошибки при нарушении схемы.
await schema.validate({});

default() и required()

Эти методы часто используются вместе.

const schema = yup.string()
  .default('guest')
  .required();

Если значение отсутствует:

schema.cast(undefined); // 'guest'

При валидации:

await schema.validate(undefined);

Результат:

'guest'

Поскольку default() подставляет значение до завершения проверки.

nullable() и default-значения

const schema = yup
  .string()
  .nullable()
  .default('empty');

Поведение:

schema.cast(undefined); // 'empty'
schema.cast(null);      // null

nullable() разрешает null, но не влияет на обработку undefined.

Использование с transform()

transform() выполняется до применения некоторых этапов валидации.

const schema = yup
  .string()
  .transform(value => value?.trim())
  .default('unknown');
schema.cast('  Alex  '); // 'Alex'
schema.cast(undefined);  // 'unknown'

Значения по умолчанию в формах

Инициализация формы

const schema = yup.object({
  login: yup.string().default(''),
  remember: yup.boolean().default(false),
});

Получение стартового состояния:

const initialValues = schema.getDefault();

Результат:

{
  login: '',
  remember: false
}

Использование с Formik

const validationSchema = yup.object({
  email: yup.string().email().required(),
  subscribe: yup.boolean().default(true),
});

const initialValues = validationSchema.getDefault();

Использование с React Hook Form

const schema = yup.object({
  username: yup.string().default('guest'),
  age: yup.number().default(18),
});

const defaultValues = schema.getDefault();

Применение default в API-моделях

const userSchema = yup.object({
  name: yup.string().required(),
  role: yup.string().default('user'),
  active: yup.boolean().default(true),
});

Входные данные:

{
  name: 'Alex'
}

После cast():

{
  name: 'Alex',
  role: 'user',
  active: true
}

Использование с when()

default() можно комбинировать с условной логикой.

const schema = yup.object({
  type: yup.string().required(),

  permissions: yup.array().when('type', {
    is: 'admin',
    then: schema => schema.default(['read', 'write']),
    otherwise: schema => schema.default(['read']),
  }),
});

Ленивые схемы и default

const schema = yup.lazy(value => {
  if (typeof value === 'string') {
    return yup.string().default('text');
  }

  return yup.number().default(0);
});

Изменяемые объекты как default

Проблемный пример:

const schema = yup.object().default({
  items: [],
});

Если объект изменяется после получения, возможны побочные эффекты.

Предпочтительный вариант:

const schema = yup.object().default(() => ({
  items: [],
}));

Функция создаёт новый объект при каждом вызове.

Глубокие структуры данных

const schema = yup.object({
  user: yup.object({
    profile: yup.object({
      firstName: yup.string().default('Unknown'),
      lastName: yup.string().default('User'),
    }),
  }),
});
schema.getDefault();

Результат:

{
  user: {
    profile: {
      firstName: 'Unknown',
      lastName: 'User'
    }
  }
}

default() и асинхронная валидация

default() работает независимо от асинхронных проверок.

const schema = yup.string()
  .default('guest')
  .test(
    'check',
    'Invalid',
    async value => {
      return value.length > 3;
    }
  );

Комбинация с strict()

В режиме strict() Yup отключает автоматические преобразования, но default() продолжает работать.

const schema = yup
  .number()
  .strict()
  .default(10);

Получение итоговой структуры объекта

const settingsSchema = yup.object({
  theme: yup.string().default('light'),

  notifications: yup.object({
    email: yup.boolean().default(true),
    sms: yup.boolean().default(false),
  }),

  tags: yup.array().of(yup.string()).default([]),
});
settingsSchema.getDefault();

Результат:

{
  theme: 'light',

  notifications: {
    email: true,
    sms: false
  },

  tags: []
}

Частые ошибки

Использование изменяемого объекта

Плохо:

default({
  items: []
})

Хорошо:

default(() => ({
  items: []
}))

Ожидание срабатывания для null

const schema = yup.string().default('test');

schema.cast(null); // null

default() не заменяет null.

Попытка использовать async-функцию

Неправильно:

default(async () => {
  return 'value';
})

default() не поддерживает асинхронные функции.

Практический пример полной схемы

import * as yup from 'yup';

const userSchema = yup.object({
  id: yup.string().default(() => crypto.randomUUID()),

  profile: yup.object({
    firstName: yup.string().default('Anonymous'),
    lastName: yup.string().default('User'),
    age: yup.number().default(18),
  }),

  settings: yup.object({
    theme: yup.string().default('light'),
    language: yup.string().default('ru'),
    notifications: yup.boolean().default(true),
  }),

  roles: yup.array()
    .of(yup.string())
    .default(['user']),

  createdAt: yup.date()
    .default(() => new Date()),
});

Получение полной структуры:

const user = userSchema.getDefault();

Пример результата:

{
  id: 'f3f8f9d0-1a2b-4f5c-8d7e-123456789abc',

  profile: {
    firstName: 'Anonymous',
    lastName: 'User',
    age: 18
  },

  settings: {
    theme: 'light',
    language: 'ru',
    notifications: true
  },

  roles: ['user'],

  createdAt: 2026-05-09T10:15:00.000Z
}
Оглавление