Lodash _.castArray() Method

Beginner
5 min read
Updated: Nov 2026
5 examples
Lang
Decorative image with the word CASTARRAY

Definition

Casts value as an array if it is not one. If value is already an array, that same reference is returned. Part of Lodash 4.x Lang.

Note: Unlike [value], this does not double-wrap existing arrays. Prefer _.toArray when you need to convert array-likes or objects into element lists.

Syntax

Call _.castArray. Start with this line.

Lodash
_.castArray([value])
CallWhat it does
_.castArray([value])Primary signature.
_.castArray(value)Check, compare, clone, or convert a value.

Prefer import castArray from "lodash/castArray" when you want a smaller bundle.

Library declarations
Lodash
_.castArray([value])

Parameters

ParameterDescription
valueOptional. Defaults to empty result when omitted

Return Value

Return ValueDescription
*Array (same ref if input was an array)

Lodash Examples

Example 1 — Official: Cast Common Values

Numbers, objects, and strings become one-element arrays.

Lodash
_.castArray(1);
// → [1]

_.castArray({ a: 1 });
// → [{ a: 1 }]

_.castArray('abc');
// → ['abc']
Try It Yourself

How It Works

  1. Not arrays. Each input fails the array check.
  2. Wrap. Lodash builds a new [value] list.
  3. Object. The object stays one element — keys are not expanded.
  4. String. Whole string is one element — not split into characters.

Example 2 — Official: null, undefined, No Args

Nullish values still become arrays; omitting args yields empty.

Lodash
_.castArray(null);
// → [null]

_.castArray(undefined);
// → [undefined]

_.castArray();
// → []
Try It Yourself

How It Works

  1. null. Wrapped as [null] — not flattened away.
  2. undefined. Wrapped as [undefined].
  3. No args. Special case returns [].
  4. Safe default. Optional params can fall through to an empty list.

Example 3 — Official: Same Array Reference

Existing arrays are returned unchanged — no copy.

Lodash
var array = [1, 2, 3];
console.log(_.castArray(array) === array);
// → true
Try It Yourself

How It Works

  1. Detect. Input is already an array.
  2. Return same. No new wrapper is allocated.
  3. Identity. === is true.
  4. Caveat. Mutating the result mutates the original array.

Example 4 — castArray vs [value]

Bracket wrap nests arrays; castArray does not.

Lodash
var list = [1, 2];

[list];
// → [[1, 2]]

_.castArray(list);
// → [1, 2]
Try It Yourself

How It Works

  1. Brackets. Always create a new outer array.
  2. Nested. An array input becomes one nested element.
  3. castArray. Sees an array and returns it as-is.
  4. Rule. Use castArray when “array or scalar” should become a flat list.

Example 5 — Normalize API Input

Accept one id or many ids with the same loop.

Lodash
function loadUsers(ids) {
  return _.castArray(ids).map(function (id) {
    return 'user:' + id;
  });
}

loadUsers(7);
// → ['user:7']

loadUsers([7, 8]);
// → ['user:7', 'user:8']
Try It Yourself

How It Works

  1. Single. 7 becomes [7].
  2. Many. [7, 8] stays a two-item list.
  3. One path. map works the same either way.
  4. Pattern. Common for “value or values” function args.
Compatibility

Browser & Runtime Support

_.castArray is a Lodash 4.x Lang helper. It runs anywhere Lodash runs — modern browsers (CDN or bundle) and Node.js / Bun / Deno with npm install lodash.

✓ Stable · Lodash 4.x

_.castArray()

Available in [email protected] full builds and the lodash/castArray modular import. Closest plain-JS pattern: Array.isArray(v) ? v : (arguments.length ? [v] : []).

100% With Lodash 4.x
Google Chrome Supported · Desktop & Mobile
Full support
Mozilla Firefox Supported · Desktop & Mobile
Full support
Apple Safari Supported · macOS & iOS
Full support
Microsoft Edge Supported · Chromium
Full support
Internet Explorer No native support · Use a polyfill
Polyfill
Opera Supported · Modern versions
Full support
Samsung Internet Supported · Android
Full support
Bun Supported · JavaScript runtime
Supported
Deno Supported · JavaScript runtime
Supported
Node.js Supported · Server runtime
Supported
Android WebView Supported · Modern WebView
Full support
_.castArray Lodash 4.x+

Bottom line: Safe for production once Lodash is loaded. Prefer import castArray from "lodash/castArray" for smaller bundles. Use it whenever APIs accept a scalar or an array of the same type.

Frequently Asked Questions

_.castArray(value) returns value unchanged if it is already an array; otherwise it returns a new one-element array containing value.
No. Primitives and objects are not mutated. If the input is already an array, the same array reference is returned.
An empty array []. Handy when an optional value should always become a safe list.
Wrapping with [value] always creates a new array — even if value is already an array, you get a nested list. castArray avoids that double wrap.
toArray converts array-likes and objects into arrays of elements. castArray only guarantees an array container around a single value (or returns an existing array).
Use import castArray from "lodash/castArray" or require("lodash/castArray") for tree-shaking friendly bundles. Full build: import _ from "lodash" then _.castArray.

Next: _.clone()

Create a shallow clone of value for safe local edits.

_.clone() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

10 people found this page helpful

Lodash Lang Methods Lodash _.clone() Method — Shallow Clone