replaceFirst — GTM Variable Template for String

VARIABLES › STRING

replaceFirst CORE String

Direct (.tpl) Apply (.tpl) Add to GTM

Replaces the first occurrence of a pattern in a string with a replacement value. Useful for simple text substitutions.

---

Examples

Replace first occurrence▶ Try

INPUT

Input String: hello world hello
Pattern to Replace: hello
Replacement Value: hi

OUTPUT

hi world hello

Remove first occurrence▶ Try

INPUT

Input String: test123test456
Pattern to Replace: test
Replacement Value:

OUTPUT

123test456

Non-string input returns original▶ Try

INPUT

Input String: 12345
Pattern to Replace: 2
Replacement Value: 9

OUTPUT

12345

---

Live Sandbox

This is what you'll see when you open this variable in Google Tag Manager. Hover the icons for details.

replaceFirst

Read-Only Try Live

Input String

💾 The input string where replacement will occur.

Supported formats:
  ✓ String

Pattern to Replace

💾 The pattern to search for in the string. Supports both literal text and regex patterns.

Supported formats:
  ✓ String (literal): "Hello", "test"
  ✓ String (regex pattern): "d+", "^start", "end$"

⚠️ Escaping note: For regex patterns, use single backslash in this UI field (e.g., d+ for digits). GTM automatically handles the escaping.

Replacement Value

💾 The replacement value to use. Use empty string to remove the first match.

Supported formats:
  ✓ String

Input Setup

Input Function (optional)

⚙️ Optional pre-processing function applied to the input before replacement (e.g., normalize case, trim whitespace).

Result Handling

Output Function (optional)

⚙️ Optional function to apply to the result string before returning it (e.g., str => str.toUpperCase(), str => str.trim()). Useful for chaining transformations on the output.

Input String string

💡 Type any text to see the result update live

🎯 Using special value — click input to type instead

Test with:

Falsy undefined null "" empty 0 false NaN

Truthy true 42 "hello" {} empty [] empty {a:1} [1,2,3]

Pattern to Replace string

Replacement Value string

🔗 Result Handling — Chain Variables

Chain apply-mode variables to the output. Each variable receives the result of the previous one.

replaceFirst()

+ Chain another variable

---

Related Variables

Same category: String

→ charAt → collapseWhitespace → concat → countWordsInString → endsWith → extract → extractFirstSegment → extractNumber → fromBase64 → indexOf → left → matchAll → matchRegex → normalizeEmail → normalizePhone → padEnd → padStart → parseJSON → replaceAll → replaceAllWithRegex → right → safeSplit → search → slice → slugify → split → startsWith → stripAccents → stripHtml → substringAfter → substringBefore → test → toBase64 → toCamelCase → toJsonString → toKebabCase → toLocaleLowerCase → toLocaleUpperCase → toLowerCase → toNumber → toSnakeCase → toStartCase → toString → toStringRepresentation → toUpperCase → toUpperFirst → trim → trimEnd → trimStart → truncate

---

Under the Hood

📜 View Implementation Code

/**
* Replaces the first occurrence of a pattern in a string with a replacement value.
*
* @param {string} data.src - The input string where replacement will occur.
* @param {string} data.pat - The pattern to search for in the string.
* @param {string} data.rep - The replacement value to use.
* @param {Function|string} [data.out] - Optional output handler: function to transform result or string with format.
*
* Direct-mode specific parameters:
* @param {Function} [data.pre] - Optional pre-processor function to transform src before replacement.
*
* @returns {string} The string with the first occurrence of the pattern replaced.
*
* @framework ggLowCodeGTMKit
*/
const replaceFirst = function(input, pattern, replacement) {
   if (typeof input === 'string' && typeof pattern === 'string' && typeof replacement === 'string') {
       return input.replace(pattern, replacement);
   }
   return input;
};
const safeFunction = fn => typeof fn === 'function' ? fn : x => x;
const out = safeFunction(data.out);
// ===============================================================================
// replaceFirst - Direct mode
// ===============================================================================
const applyCast = (castFn, value) => safeFunction(castFn)(value);
const processedInput = applyCast(data.pre, data.src);
return out(replaceFirst(processedInput, data.pat, data.rep));
// ===============================================================================
// replaceFirst(...) – Apply Mode
// ===============================================================================
/*
return function(value, pattern, replacement) {
   return out(replaceFirst(value, data.pat, data.rep));
};
*/

🧪 View Test Scenarios (8 tests)

✅ '[example] Replace first occurrence'
✅ Replace word in middle of string - should replace only first occurrence
✅ '[example] Remove first occurrence'
✅ Pattern not found - should return original string
✅ Empty string input - should return empty string
✅ Replace special characters - should replace first occurrence
✅ Replace with longer string - should work correctly
✅ '[example] Non-string input returns original'