Ramda.js R.head() Method

Beginner
5 min read
Updated: Nov 2026
5 examples
List

Definition

R.head(list) returns the first element of an array, or the first character of a string. If there is nothing there, you get undefined instead of an error (official Ramda docs). It is exactly R.nth(0, list).

Stable since v0.1.0: R.head is not deprecated, experimental, or non-standard. Other libraries call the same idea first.

Syntax

Call R.head. Start with this line.

Ramda
R.head(list)
CallWhat it does
R.head(list)Primary signature.
R.head(...)Call the list helper.

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

Library declarations
Ramda
R.head(list)

Parameters

ParameterDescription
listRequired. Array or String. The value to read the first item (or character) from

Return Value

Return ValueDescription
*The value returned by R.head().

Ramda Examples

Example 1 — Official Samples

The first item of an array, the first character of a string, and an empty array — straight from the Ramda docs.

Ramda
console.log(R.head(['fi', 'fo', 'fum'])); // fi
console.log(R.head('abc'));               // a
console.log(R.head([]));                  // undefined
Try It Yourself

How It Works

  1. Array. Index 0 of ['fi', 'fo', 'fum'] is 'fi'.
  2. String. A string is read like a list of characters, so the first one is 'a'.
  3. Empty. [] has no index 0, so R.head returns undefined instead of throwing.
  4. Read-only. None of the inputs is changed.

Example 2 — Build Initials from Names

Because R.head is a plain function, you can hand it straight to R.map.

Ramda
const names = ['Ada', 'Grace', 'Linus'];

const initials = R.map(R.head, names);

console.log(JSON.stringify(initials)); // ["A","G","L"]
console.log(initials.join(''));        // AGL
Try It Yourself

How It Works

  1. Map. R.map calls R.head once for each name.
  2. First character. 'Ada' → 'A', 'Grace' → 'G', 'Linus' → 'L'.
  3. No wrapper needed. You pass R.head directly instead of writing (name) => name[0].
  4. Join. join('') glues the letters into 'AGL'.

Example 3 — Find the Top Scorer in a Pipeline

Sort, reverse, then take the first item — R.head is a natural last step in R.pipe.

Ramda
const players = [
  { name: 'Ana', score: 72 },
  { name: 'Ben', score: 95 },
  { name: 'Cy', score: 88 }
];

const topPlayer = R.pipe(R.sortBy(R.prop('score')), R.reverse, R.head);

const best = topPlayer(players);
console.log(best.name + ' (' + best.score + ')'); // Ben (95)
console.log(players[0].name);                     // Ana
Try It Yourself

How It Works

  1. Sort. R.sortBy(R.prop('score')) orders players from lowest to highest score.
  2. Reverse. R.reverse puts the highest score first.
  3. Head. R.head picks that first player: Ben with 95.
  4. Nothing mutated. Each step returns a new array, so players[0] is still Ana.

Example 4 — A Safe Fallback for Empty Lists

Turn a possible undefined into a sensible default with R.defaultTo.

Ramda
const firstOr = (fallback) => R.pipe(R.head, R.defaultTo(fallback));

const firstTask = firstOr('Nothing to do');

console.log(firstTask(['Email Ana', 'Fix bug'])); // Email Ana
console.log(firstTask([]));                       // Nothing to do
Try It Yourself

How It Works

  1. Head first. R.head returns the first task, or undefined for an empty list.
  2. Then default. R.defaultTo(fallback) replaces undefined (or null/NaN) with the fallback.
  3. Reusable. firstOr('Nothing to do') builds a ready-to-use helper.
  4. Result. A real task passes through unchanged; an empty list shows the fallback text.

Example 5 — head vs last, nth, take, tail

Five helpers, one list. Notice which ones return a single item and which return an array.

Ramda
const nums = [5, 6, 7];

console.log(R.head(nums));                    // 5
console.log(R.last(nums));                    // 7
console.log(R.nth(0, nums));                  // 5
console.log(JSON.stringify(R.take(1, nums))); // [5]
console.log(JSON.stringify(R.tail(nums)));    // [6,7]
Try It Yourself

How It Works

  1. Single items. R.head → 5, R.last → 7, and R.nth(0) → 5, the same as head.
  2. Array of one. R.take(1) returns [5], an array — not the item itself.
  3. The rest. R.tail drops the head and returns [6, 7].
  4. Together. head + tail split a list into “first” and “rest”.

Browser & Runtime Support

R.head() is plain JavaScript inside Ramda 0.1.0+. It only reads index 0, so support depends only on loading Ramda.

✓ Ramda 0.1.0+ · Any JS runtime

Ramda.js R.head()

The UMD build (ramda.min.js) is compiled to ES5 syntax, so it runs in Chrome, Firefox, Safari, and Edge. Via npm it works in Node.js, Deno, and Bun with require or import.

100% With Ramda loaded
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
R.head() Universal

Bottom line: Safe in any project that loads Ramda. Use ramda.min.js from a CDN in the browser, or npm install ramda for Node, Deno, and Bun. These labs load [email protected].

Frequently Asked Questions

R.head(list) returns the first element of an array, or the first character of a string. It is the same as R.nth(0, list). Some libraries call this function first.
undefined. It never throws for an empty array, so check with R.isEmpty first if undefined could also be a real first value, as in [undefined].
R.head gives the first item and R.last gives the last item. R.nth(i, list) picks any index, so R.nth(0, list) equals R.head(list). R.tail returns a new array of everything except the first item.
They return the same value. R.head is a function, so it can be passed to R.map, R.pipe, or R.compose without writing an arrow function, for example R.map(R.head, names).
The Ramda docs say undefined, and that is what the minified CDN build and Ramda v0.31.0+ return. The npm build of v0.30.1 and earlier returns an empty string instead, so test for an empty result with R.isEmpty or a falsy check.
No. R.head has been a stable Ramda List function since v0.1.0. It is not deprecated, experimental, or non-standard.

Next: R.includes()

Check whether a list or string contains a value.

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