Ramda.js R.renameKeys() Method

Beginner
5 min read
Updated: Nov 2026
5 examples
Object

Definition

Ramda’s R.renameKeys() answers a dictionary question: how do I rename a few own keys and leave the rest? You pass a mapping of old name to new name, then an object. You get a new object. The original is not mutated.

The official sample is the whole idea. mapping = {name: 'firstName', address: 'street'} and obj = {name: 'John', city: 'Paris'}. R.renameKeys(mapping, obj) is {firstName: 'John', city: 'Paris'}. Need a function on every key? That is R.mapKeys. Need the lower-level rebuild of pairs? That is R.rebuild. Need to rewrite values instead? That is R.map.

Syntax

Call R.renameKeys. Start with this line.

Ramda
R.renameKeys(mapping, obj)
CallWhat it does
R.renameKeys(mapping, obj)Primary signature.
R.renameKeys(...)Call the object helper.

Prefer import { renameKeys } from "ramda" when you want a named import.

Library declarations
Ramda
R.renameKeys(mapping, obj)

Parameters

ParameterDescription
mappingRequired. Object. Pairs of existing keys with new ones, as {oldKey: newKey}. Extra names that are not on obj are ignored.
objRequired. Object. The record whose own keys should be rewritten. Prototype names are skipped. The source is never mutated.

Return Value

Return ValueDescription
ObjectA new object. Mapped keys use the new names. Unmapped keys keep the old names. Values stay. If two keys become one name, the last processed value wins.

Ramda Examples

📚 Getting Started

The official John / Paris sample, then unmapped keys, extra mapping names, and no mutation.

Example 1 — Official Rename Mapping

name becomes firstName. city is not in the mapping, so it stays. Unused address does nothing.

Ramda
const mapping = { name: 'firstName', address: 'street' };
const obj = { name: 'John', city: 'Paris' };

R.renameKeys(mapping, obj);
//=> {firstName: 'John', city: 'Paris'}
Try It Yourself

How It Works

Ramda looks up each own key in mapping. name is present, so it becomes firstName. city is not, so it stays. address is only in the mapping, so it never appears. That is the docs sample from ramdajs.com.

Example 2 — Unmapped Keys and No Mutation

The leftover is a new object. The source still has name. Extra mapping names are ignored.

Ramda
const mapping = { name: 'firstName', address: 'street' };
const orig = { name: 'John', city: 'Paris' };
const copy = R.renameKeys(mapping, orig);

copy;
//=> {firstName: 'John', city: 'Paris'}

orig;
//=> {name: 'John', city: 'Paris'}

copy === orig;
//=> false
Try It Yourself

How It Works

renameKeys always allocates a new object. Nested values stay shared by reference, the same shallow rule as mapKeys. The mapping is a lookup, not a whitelist of leftover keys.

📈 Practical Patterns

Compare mapKeys, then a curried helper mapped over rows, then collisions and an empty mapping.

Example 3 — vs mapKeys

A dictionary changes listed names. A function changes every name.

Ramda
const obj = { name: 'John', city: 'Paris' };

R.renameKeys({ name: 'firstName' }, obj);
//=> {firstName: 'John', city: 'Paris'}

R.mapKeys(R.toUpper, obj);
//=> {NAME: 'John', CITY: 'Paris'}
Try It Yourself

How It Works

Internally, renameKeys is mapKeys with a lookup: if the old key is in the mapping, use the new name, else keep the old name. Need every key uppercased? Stay on R.mapKeys.

Example 4 — Curry and Map

Fill the mapping to map over rows. Each leftover uses firstName.

Ramda
const asApi = R.renameKeys({ name: 'firstName' });

R.map(asApi, [
  { name: 'Ada', city: 'London' },
  { name: 'Bo', city: 'Paris' }
]);
//=> [{firstName: 'Ada', city: 'London'}, {firstName: 'Bo', city: 'Paris'}]
Try It Yourself

How It Works

Because renameKeys is arity 2, filling the mapping leaves a function of one object. Rest syntax would need an arrow wrapper on every row.

Example 5 — Collisions, Empty Mapping, Empty Object

Two old keys to one new name keep the last processed value. An empty mapping copies own keys. An empty object stays empty.

Ramda
R.renameKeys({ a: 'x', b: 'x' }, { a: 1, b: 2 });
//=> {x: 2}

R.renameKeys({}, { name: 'John' });
//=> {name: 'John'}

R.renameKeys({ name: 'firstName' }, {});
//=> {}
Try It Yourself

How It Works

Own-key order is usually insertion order. b is processed after a, so x is 2. An empty mapping never finds a hit, so every own key is copied. There is nothing to rename on {}.

Browser Support

R.renameKeys() is ordinary JavaScript once Ramda 0.31 or later is loaded. Logos use the shared browser-image-sprite.png sprite from this project.

✓ Ramda 0.31.0+ · Any JS runtime

Ramda.js R.renameKeys()

Load Ramda 0.31.0 or later via CDN or npm, then call R.renameKeys with a mapping object and a record. No extra browser API is required.

100% With Ramda 0.31.0+
Google Chrome All versions · Desktop & Mobile
Full support
Mozilla Firefox All versions · Desktop & Mobile
Full support
Apple Safari All versions · macOS & iOS
Full support
Microsoft Edge All versions · Chromium & Legacy
Full support
Internet Explorer IE 6+ · Legacy environments
Full support
Opera All modern versions
Full support
R.renameKeys() Universal

Bottom line: Safe in any project that includes Ramda 0.31.0 or later. Use a CDN build such as ramda.min.js in the browser or install ramda from npm for Node. These labs use [email protected]. Ramda 0.30.x does not include renameKeys.

Frequently Asked Questions

R.renameKeys(mapping, obj) returns a new object whose own keys are renamed when they appear in mapping as {oldKey: newKey}. Unmapped keys stay. Added in v0.31.0. The original object is not mutated.
mapping = {name: 'firstName', address: 'street'} and obj = {name: 'John', city: 'Paris'}. R.renameKeys(mapping, obj) is {firstName: 'John', city: 'Paris'}.
renameKeys uses a dictionary of old names to new names. mapKeys uses a function on every key. rebuild is the lower-level rebuild of key-value pairs. Internally renameKeys is mapKeys with has(key, mapping) ? mapping[key] : key.
They keep their old names and values. Extra names in the mapping that are not on the object are ignored.
The last processed key wins, because renameKeys is built on mapKeys. Earlier values for that new name are dropped.
No. R.renameKeys is a stable Ramda object helper from v0.31.0. It is not deprecated, experimental, or non-standard. It is missing from Ramda 0.30.x.

Continue to R.set()

Learn how to write a value through a lens using Ramda R.set().

R.set() 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.

6 people found this page helpful