Tutorials Guides Reference Articles Cookbooks About

stringr::str_replace() 

str_replace(string, pattern, replacement)
Returns: character · Updated March 16, 2026 · Tidyverse
stringr string replace regex tidyverse

The str_replace() function from stringr replaces the first occurrence of a pattern in a string. For replacing all occurrences, use str_replace_all(). These functions are essential for text cleaning, formatting, and transformation tasks.

Syntax

str_replace(string, pattern, replacement)
str_replace_all(string, pattern, replacement)

Parameters

ParameterTypeDefaultDescription
stringcharacterRequiredA character vector to modify
patternpatternRequiredA pattern to find (regex, fixed, or coll)
replacementcharacterRequiredThe replacement string

Examples

Basic usage

library(stringr)

# Replace first occurrence
str_replace("hello world", "world", "R")
# [1] "hello R"

# Replace all occurrences
str_replace_all("babababab", "b", "a")
# [1] "aaaaa"

Using with dplyr mutate

library(dplyr)

df <- data.frame(
  name = c("john_smith", "jane_doe", "bob_jones")
)

# Replace underscores with spaces
df %>% mutate(name_clean = str_replace_all(name, "_", " "))
#        name   name_clean
# 1 john_smith  john smith
# 2   jane_doe    jane doe
# 3   bob_jones   bob jones

Regex patterns

# Replace digits
str_replace_all("order123", "\\d+", "N")
# [1] "orderN"

# Replace multiple spaces with single space
str_replace_all("too   many    spaces", "\\s+", " ")
# [1] "too many spaces"

# Replace at word boundaries
str_replace_all("the cat and the dog", "\\bthe\\b", "a")
# [1] "a cat and a dog"

Capture groups

# Use parentheses to capture groups, reference with \\1, \\2, etc.
str_replace("2026-03-16", "(\\d{4})-(\\d{2})-(\\d{2})", "\\3/\\2/\\1")
# [1] "16/03/2026"

# Swap first and last names
str_replace("Doe, John", "(\\w+), (\\w+)", "\\2 \\1")
# [1] "John Doe"

Case conversion

# Convert to lowercase
str_replace("HELLO", "HELLO", "hello")
# [1] "hello"

# Toggle case (upper to lower, lower to upper)
str_replace("Hello World", "([a-z])([A-Z])", "\\1\\2")
# This requires more complex patterns

HTML cleaning

# Remove HTML tags
str_replace_all("<p>Hello</p>", "<[^>]+>", "")
# [1] "Hello"

# Replace URLs with placeholder
str_replace_all("Visit https://example.com today", 
                "https?://[^\\s]+", "[URL]")
# [1] "Visit [URL] today"

Backreferences and Special Cases

Backreferences with named groups

# Named capture groups
str_replace("john@example.com", 
            "(?<user>[^@]+)@(?<domain>.+)", 
            "\\<domain>/\\<user>")
# [1] "example.com/john"

Special replacement functions

# Use a function as replacement for dynamic substitution
str_replace_all(c("apple", "banana", "cherry"), 
                "^[a-z]", 
                toupper)
# [1] "Apple" "Banana" "Cherry"

# Use with dplyr
df <- data.frame(
  text = c("cat", "dog", "bird")
)

df %>% mutate(
  upper = str_replace_all(text, "^[a-z]", toupper)
)
#   text  upper
# 1  cat   Cat
# 2  dog   Dog
# 3 bird  Bird

Common Use Cases

Data cleaning

# Clean phone numbers
str_replace_all("+1-555-123-4567", "[^0-9]", "")
# [1] "15551234567"

# Normalize whitespace
str_replace_all("  hello   world  ", "\\s+", " ")
# [1] " hello world "

Text normalization

# Standardize dates
str_replace_all(c("03/16/2026", "2026-03-16", "16.03.2026"),
               "\\d+", "DD")
# [1] "DD/DD/DDDD" "DD-DD-DD" "DD.DD.DDDD"

String transformation

# Convert snake_case to camelCase
str_replace_all("hello_world_test", "_([a-z])", "\\U\\1")
# [1] "helloWorldTest"

# Remove prefixes
str_replace("package_function", "^[^_]+_", "")
# [1] "function"

See Also