# regex.replace()

`regex.replace(haystack, pattern, replacement)` replaces the first occurrence of a regex pattern in a string with a replacement string.

## Returns

* if `haystack` and `replacement` are strings and `pattern` matches, returns a new string with the first match replaced by `replacement`.
* otherwise, returns `null`.

## Examples

```javascript
// remove leading whitespace
regex.replace(text, /^\s+/, "")
```