Lay one string on top of another, with an optional offset

Quick Take

import { strict as assert } from "assert";
import { overlap } from "string-overlap-one-on-another";

  overlap("aaa", "bbb", { offset: -2 }),



In essence,

//           aaa
// + bbb (negative offset of 2 means it's pushed to the left by 2 places)
// --
// = bbbaa


overlap(str1, str2, [opts])

API - Input

API for both methods is the same:

Input argument Type Obligatory? Description
str1 String yes The string which will be put "under" str2
str2 String yes The string which will be put "over" str1
opts Plain object no An Optional Options Object. See its API below, in a separate table.

Optional Options Object

Optional Options Object's key Type of its value Default Description
offset Positive or negative integer or zero 0 It instructs to offset the top string by this many characters to the right (if a positive number) or to the left (if a negative number). The default value is zero.
offsetFillerCharacter String `` (space) If the offset value (character amount to push left) pushes the str2 outside the boundaries of str1 and not even there's no overlap, but there is a gap, this gap is formed out of these characters. The default is a single space.

Here are all the defaults in one place:

offset: 0, // how many characters str2 is to the right? (negative means it's off to the left)
offsetFillerCharacter: " " // how many characters str2 is to the right? (negative means it's off to the left)

Edge cases

The algorithm is the following:

  1. If one and only one of two input strings is zero-long, the other string is returned as a result.
  2. If both input strings are empty, an empty string is returned.
  3. If both input strings are non-empty, the result is second string overlaid on the first, considering the offset.


See it in the monorepo opens in a new tab, on GitHub.


To report bugs or request features or assistance, raise an issue on GitHub opens in a new tab.

Any code contributions welcome! All Pull Requests will be dealt promptly.


MIT opens in a new tab

Copyright © 2010–2021 Roy Revelt and other contributors

Related packages:

📦 detergent 8.0.1
Extracts, cleans and encodes text
📦 string-match-left-right 8.0.1
Match substrings on the left or right of a given index, ignoring whitespace
📦 string-find-heads-tails 5.0.1
Finds where are arbitrary templating marker heads and tails located
📦 string-remove-duplicate-heads-tails 6.0.1
Detect and (recursively) remove head and tail wrappings around the input string
📦 string-process-comma-separated 3.0.1
Extracts chunks from possibly comma or whatever-separated string
📦 string-split-by-whitespace 3.0.1
Split string into array by chunks of whitespace
📦 string-collapse-leading-whitespace 6.0.1
Collapse the leading and trailing whitespace of a string