Array.prototype.join()

Concatenates all array elements into a single string, separated by the given separator.

Signature
join()
join(separator)
  • Added in JavaScript ES1

Parameters

ParameterTypeDescription
$separatoroptionalstring= ","A string to separate each pair of adjacent elements of the array. If omitted, the array elements are separated with a comma (","). Non-string values are converted to a string.

Return value

stringA string with all array elements joined. If array.length is 0, the empty string is returned.

Errors

Throws a TypeError if an element is a Symbol or an object whose toString/valueOf cannot produce a primitive.

Changelog

  • PHP ES1Present on Array.prototype from the first edition of the language.
  • PHP ES5Cyclic references are ignored rather than causing infinite recursion in engines that implement the guard.

See also

Array.prototype.concat()Array.prototype.reverse()Array.prototype.slice()Array.prototype.sort()

join() flattens an array into one string, inserting the separator between adjacent elements. It is the inverse of splitting a string, and the default separator is a comma — the same thing toString() and implicit string coercion do.

When to reach for it

Reach for it to build paths, CSV rows, class name lists, SQL fragments, or any delimited text. It is faster and clearer than accumulating with += in a loop, and it handles the "no trailing separator" problem for free. For a newline-delimited block, lines.join("\n") beats manual concatenation every time.

What trips people up

null and undefined elements become the empty string, not the text "null", so [1, null, 2].join("-") is "1--2" with a visible double separator. Empty slots in sparse arrays behave the same way. Filter first if blank entries are unwanted.

Nested arrays are joined recursively with commas regardless of your separator, because their toString() runs. And a passing a non-string separator coerces it, so join(0) produces "102" from [1, 2].

Example

Try it yourself
Loading editor…
Press Run to execute the code.

When to use it

  • Build a file path or URL segment list from parts
  • Render a comma-separated list of tags for display
  • Produce a CSV row from an array of field values
  • Assemble a multi-line block of text from an array of lines

Frequently asked questions

What is the default separator for join()?

A comma. Calling join() with no arguments produces the same string as toString(), so [1,2].join() returns "1,2".

Why does join() show empty gaps instead of "null"?

The specification converts null and undefined elements to the empty string, so they contribute nothing between separators; filter them out first if you want them omitted entirely.

How do I join an array with newlines?

Call arr.join("\n"), which puts a line break between elements without adding a trailing one at the end of the string.

More examples

Building a CSV row

Mapping through a quoting function before joining handles the null and any embedded quotes. The final join with a newline assembles the two rows into one CSV document.

Example · javascript
const headers = ["id", "name", "email"];
const row = [7, "Ada Lovelace", null];

const quote = (v) => `"${String(v ?? "").replace(/"/g, '""')}"`;

console.log(headers.join(","));
console.log(row.map(quote).join(","));
console.log([headers.join(","), row.map(quote).join(",")].join("\n"));

Dropping empty entries first

The raw join leaves doubled and trailing spaces where the empty values were. Filtering with Boolean removes null, undefined, and empty strings so the separator appears only between real values.

Example · javascript
const classes = ["btn", null, "btn-primary", undefined, ""];

console.log(classes.join(" "));                    // 'btn  btn-primary  '
console.log(classes.filter(Boolean).join(" "));    // 'btn btn-primary'

const tags = ["a", , "c"];
console.log(tags.join("|"));                       // 'a||c' — hole is blank

join() versus toString() and template literals

The first three lines produce the same string because array coercion delegates to join with the default comma. Only join lets you choose the separator, and a non-string separator is coerced to a string first.

Example · javascript
const nums = [1, 2, 3];

console.log(nums.join());       // '1,2,3'
console.log(nums.toString());   // '1,2,3' — identical
console.log(`${nums}`);         // '1,2,3' — implicit coercion
console.log(nums.join(" + "));  // '1 + 2 + 3'
console.log(nums.join(0));      // '10203' — separator is coerced

Related

array concatarray reversearray slicearray sortarray push

Discussion

  • Be the first to comment on this lesson.