Underscore.js _.defaults() Method

Beginner
5 min read
Updated: Nov 2026
5 examples
Object

Definition

Returns object after filling its undefined properties with the first value present in the following list of defaults objects (official Underscore docs). Stable Object helper — not deprecated.

Pass the required arguments shown below. Underscore object helpers usually return a new value — check whether the source object is mutated.

Syntax

Call _.defaults. Start with this line.

Underscore
_.defaults(object, *defaults)
CallWhat it does
_.defaults(object, *defaults)Primary signature.
_.defaults(...)Call with the arguments your case needs.

Load Underscore with import _ from "underscore" (or the UMD CDN build) so these helpers are available as _.

Library declarations
Underscore
_.defaults(object, *defaults)

Parameters

ParameterDescription
objectRequired. Target to fill (mutated and returned)
*defaultsRequired. One or more source objects of fallback values

Return Value

Return ValueDescription
*Same object reference

Underscore.js Examples

Example 1 — Fill Missing Keys

Official-style fill: set keys win; missing keys take the default.

Underscore
var iceCream = { flavor: "chocolate" };

_.defaults(iceCream, { flavor: "vanilla", sprinkles: "lots" });

iceCream;
// → { flavor: "chocolate", sprinkles: "lots" }
Try It Yourself

How It Works

  1. Target. iceCream already has flavor.
  2. Skip. Default "vanilla" is ignored for flavor.
  3. Fill. sprinkles was missing → becomes "lots".
  4. Return. Same object is mutated and returned.

Example 2 — Existing Values Stay

Only the missing key gets a default; set values are never overwritten.

Underscore
var settings = { pageSize: 50, theme: "dark" };

_.defaults(settings, { pageSize: 20, theme: "light", sort: "name" });

settings;
// → { pageSize: 50, theme: "dark", sort: "name" }
Try It Yourself

How It Works

  1. Keep. pageSize and theme already exist.
  2. Ignore. Defaults 20 and "light" are skipped.
  3. Add. sort was undefined → filled with "name".
  4. Rule. Defaults never clobber set keys.

Example 3 — Multiple Defaults (First Wins)

Stack several defaults objects; the earliest present value fills each key.

Underscore
var config = { lang: "fr" };

_.defaults(config,
  { theme: "light", lang: "en" },
  { theme: "dark", debug: false }
);

config;
// → { lang: "fr", theme: "light", debug: false }
Try It Yourself

How It Works

  1. Keep. lang: "fr" stays; "en" is ignored.
  2. First fill. theme comes from the first defaults object → "light".
  3. Skip later. Second object’s "dark" does not replace theme.
  4. Still missing. debug is filled from the second object.

Example 4 — Falsy Values Are Kept

0, false, and null are real values — only undefined is filled.

Underscore
var prefs = { count: 0, enabled: false, note: null };

_.defaults(prefs, { count: 10, enabled: true, note: "hi", extra: "x" });

prefs;
// → { count: 0, enabled: false, note: null, extra: "x" }
Try It Yourself

How It Works

  1. Falsy ≠ missing. 0, false, and null stay.
  2. Check. Underscore tests === undefined, not truthiness.
  3. Fill. Only extra was undefined → set to "x".
  4. Pitfall. Do not expect null to trigger a default.

Example 5 — Safe Options Pattern

Apply presets without mutating the caller’s object.

Underscore
function createGrid(options) {
  options = _.defaults({}, options, { columns: 3, gap: 8, border: true });
  return options;
}

createGrid({ columns: 6 });
// → { columns: 6, gap: 8, border: true }
Try It Yourself

How It Works

  1. Fresh target. Start with {} so the caller’s object is untouched.
  2. User wins. Copy options next — columns: 6 is set.
  3. Presets last. Defaults fill only still-undefined keys.
  4. Result. Merged config object, ready to use.

Browser & Runtime Support

_.defaults ships with Underscore.js (1.x). It runs anywhere Underscore runs — modern browsers (CDN or bundle) and Node.js / Bun / Deno with npm install underscore.

✓ Stable · Underscore 1.x

_.defaults()

Available in [email protected] (UMD / ESM). Works in evergreen browsers and current Node LTS when Underscore is loaded.

100% With Underscore 1.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
_.defaults Underscore 1.x+

Bottom line: Safe for production once Underscore is on the page or in your bundle. Not a native browser API — load Underscore first. Prefer a pinned CDN version (e.g. [email protected]).

Frequently Asked Questions

_.defaults(object, *defaults) fills undefined properties on object from one or more defaults objects, then returns that same object. Ideal for option fallbacks.
Yes. It mutates and returns the first argument. To keep the caller’s object untouched, use _.defaults({}, options, presets).
Only keys that are undefined (including missing keys). Values like null, false, 0, or '' stay as-is.
They are applied in order; the first present value wins. Later defaults do not override a key already filled.
_.extend overwrites existing keys. _.defaults only fills undefined keys and never clobbers set values.
No. It is a shallow, top-level fill. Nested objects are assigned by reference, not merged recursively.

Next: _.clone()

Create a shallow copy of an object or array.

_.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.

12 people found this page helpful