Recursively assigns source properties to the destination for leaves that are still undefined. Plain objects and arrays are walked; defined values win. Since Lodash 3.10.0.
Pass the object and path or keys shown below. Check whether the helper mutates or returns a new object.
Call _.defaultsDeep. Start with this line.
_.defaultsDeep(object, ...sources)| Call | What it does |
|---|---|
_.defaultsDeep(object, ...sources) | Primary signature. |
_.defaultsDeep(object) | Work with an object’s keys, values, or paths. |
Prefer import defaultsDeep from "lodash/defaultsDeep" when you want a smaller bundle.
_.defaultsDeep(object, ...sources)| Parameter | Description |
|---|---|
| object | Required. Destination (mutated and returned) |
| ...sources | Optional. Default providers (left → right) |
| Return Value | Description |
|---|---|
| * | The value returned by _.defaultsDeep(). |
Existing nested values win; new leaves come from sources.
_.defaultsDeep({ a: { b: 2 } }, { a: { b: 1, c: 3 } });
// → { a: { b: 2, c: 3 } }a.b = 2.a.2; source 1 is ignored.3._.defaultsA defined nested object stops shallow defaults; deep walk fills inside.
var base = { user: { name: "Guest" } };
var fill = { user: { name: "Admin", role: "viewer" } };
_.defaults(_.cloneDeep(base), fill);
// → { user: { name: "Guest" } }
_.defaultsDeep(_.cloneDeep(base), fill);
// → { user: { name: "Guest", role: "viewer" } }user is already an object → whole branch kept.user."Guest"; role is filled.Arrays are not opaque — each index is compared like a leaf.
_.defaultsDeep({ tags: ["a", "b"] }, { tags: ["x", "y", "z"] });
// → { tags: ["a", "b", "z"] }
_.defaultsDeep({ tags: undefined }, { tags: ["x", "y", "z"] });
// → { tags: ["x", "y", "z"] }"a", "b"."z".null vs undefinedOnly undefined leaves are treated as gaps.
_.defaultsDeep(
{ a: { b: null, c: undefined } },
{ a: { b: 1, c: 2, d: 3 } }
);
// → { a: { b: null, c: 2, d: 3 } }null → kept (not a gap).undefined → filled with 2.3.null first if you want it replaced too._.merge (Safe {} Pattern)defaultsDeep keeps destination leaves; merge lets sources overwrite.
var user = { a: { b: 2 } };
var src = { a: { b: 1, c: 3 } };
_.defaultsDeep({}, user, src);
// → { a: { b: 2, c: 3 } }
_.merge({}, user, src);
// → { a: { b: 1, c: 3 } }user.b: 2 wins; c is filled.b to 1._.defaultsDeep is a Lodash Object helper (since 3.10.0). It runs anywhere Lodash 4.x runs — modern browsers (CDN or bundle) and Node.js / Bun / Deno with npm install lodash.
Available in [email protected] full builds and the lodash/defaultsDeep modular import. Works in evergreen browsers and current Node LTS when Lodash is installed.
Bottom line: Safe for production once Lodash is loaded. Prefer import defaultsDeep from "lodash/defaultsDeep". Use shallow _.defaults when nesting is not needed.
Return the first own key whose value matches a predicate.
11 people found this page helpful