Lodash _.cloneWith() method
What you’ll learn
- How
_.cloneWith(value, customizer)shallow-clones and how thecustomizeris consulted (usually for the root value, not each field). - Why nested objects usually remain shared compared with _.cloneDeepWith().
- How this differs from plain _.clone().
- Patterns for replacing whole roots (objects or arrays) versus using
cloneDeepWithfor nested hooks.
Prerequisites
Read _.clone() for shallow-copy basics and _.cloneDeepWith() if you need the deep variant.
- You understand object references and one-level versus nested copying.
- You can open Try-it labs in the browser or run snippets in Node.
Overview
_.cloneWith builds a shallow clone and invokes your customizer for visited clone steps—for a plain object or array you typically handle the root once (not each nested field). Use cloneDeepWith when you need per-node recursion.
Shallow base
New outer array or object; nested structures stay aliased unless replaced.
Customizer hook
Return a substitute value or undefined to accept Lodash defaults.
Upgrade path
Need recursion plus hooks? Switch to cloneDeepWith.
Syntax
_.cloneWith(value, [customizer])- value: value to clone (object, array, etc.).
- customizer: invoked to produce the clone of each visited value
(value, key, object)—return a replacement orundefinedfor Lodash defaults. For a plain object or array root, shallowcloneWithtypically hits the customizer once at the root (key oftenundefined), not once per property. - Returns: shallow clone; use the customizer to swap the whole root or rely on
cloneDeepWithfor per-node hooks.
Shallow clone, nested shared
Without a customizer, behavior matches a shallow copy: new top object, nested refs unchanged.
import cloneWith from "lodash/cloneWith";
var source = { id: 1, meta: { level: 2 } };
var copy = cloneWith(source);
console.log(copy !== source); // true
console.log(copy.meta === source.meta); // trueReplace the root array
For an array root, the customizer receives the whole array once—return a new array to control the shallow result.
import cloneWith from "lodash/cloneWith";
var source = [1, 2, 3];
var copy = cloneWith(source, function (value) {
if (Array.isArray(value)) {
return value.map(function (n) {
return n * 2;
});
}
});
console.log(copy); // [2, 4, 6]Adjust fields via root replacement
Because shallow cloneWith asks the customizer for the whole object first, bump id by returning a new plain object (use cloneDeepWith if you need per-property callbacks).
import cloneWith from "lodash/cloneWith";
var source = { id: 1, label: "unit" };
var copy = cloneWith(source, function (value) {
if (value !== null && typeof value === "object" && !Array.isArray(value)) {
return Object.assign({}, value, { id: value.id + 10 });
}
});
console.log(copy.id); // 11📋 _.cloneWith vs related APIs
| Method | Depth | Customizer |
|---|---|---|
_.cloneWith(value, fn) | Shallow | Yes |
_.clone(value) | Shallow | No |
_.cloneDeepWith(value, fn) | Deep | Yes |
Pitfalls to avoid
Expecting deep isolation
Nested objects remain shared unless you return new nested objects yourself.
Expecting per-property callbacks
Shallow cloneWith usually invokes the customizer on the root value first. Use cloneDeepWith for recursive per-node hooks.
Heavy customizers
Keep customizer logic cheap—especially when returning rebuilt objects or arrays.
❓ FAQ
Summary
- Purpose: shallow clone with optional per-property overrides.
- Customizer: return a replacement or
undefinedfor defaults. - Next: browse Lodash _.conformsTo() for more Lang helpers.
Unlike _.cloneDeepWith, _.cloneWith only performs a shallow copy—nested objects stay shared unless your customizer replaces them.
About the author
6 people found this page helpful