https://github.com/iansinnott/react-string-replace
A simple way to safely do string replacement with React components
https://github.com/iansinnott/react-string-replace
react react-components string-manipulation
Last synced: about 2 months ago
JSON representation
A simple way to safely do string replacement with React components
- Host: GitHub
- URL: https://github.com/iansinnott/react-string-replace
- Owner: iansinnott
- License: mit
- Created: 2016-02-03T23:22:02.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2024-02-27T14:46:43.000Z (about 2 years ago)
- Last Synced: 2025-05-10T01:03:40.580Z (10 months ago)
- Topics: react, react-components, string-manipulation
- Language: JavaScript
- Homepage:
- Size: 722 KB
- Stars: 661
- Watchers: 5
- Forks: 55
- Open Issues: 26
-
Metadata Files:
- Readme: readme.md
- License: license
Awesome Lists containing this project
- awesome - react-string-replace
README
# React String Replace
[](https://www.npmjs.com/package/react-string-replace)
A simple way to safely do string replacement with React components. Zero dependencies.
> Aka turn a string into an array of React components
## Install
```sh
npm install react-string-replace
# or
yarn add react-string-replace
# or
bun add react-string-replace
```
## Usage
First, import the lib. Both `require` and `import` are supported.
```js
import reactStringReplace from "react-string-replace";
// OR
const reactStringReplace = require("react-string-replace");
```
Examples will use `import` since it is more common in the React ecosystem.
### Simple Example
```js
import reactStringReplace from 'react-string-replace';
reactStringReplace('whats your name', 'your', (match, i) => (
{match}
));
// => [ 'whats ', your, ' name' ]
```
### More realistic example
Highlight all digits within a string by surrounding them in span tags:
```js
reactStringReplace("Apt 111, phone number 5555555555.", /(\d+)/g, (match, i) => (
{match}
));
// =>
// [
// 'Apt ',
// 111,
// ', phone number ',
// 5555555555,
// '.'
// ]
```
### Within a React component
```jsx
import reactStringReplace from "react-string-replace";
function HighlightNumbers() {
const content = "Hey my number is 555-555-5555.";
return (
{reactStringReplace(content, /(\d+)/g, (match, i) => (
{match}
))}
);
}
```
### Multiple replacements on a single string
You can run multiple replacements on one string by calling the function multiple times on the returned result. For instance, if we want to match URLs, @-mentions and hashtags in a string we could do the following:
```js
import reactStringReplace from "react-string-replace";
const text =
"Hey @ian_sinn, check out this link https://github.com/iansinnott/ Hope to see you at #reactconf";
let replacedText;
// Match URLs
replacedText = reactStringReplace(text, /(https?:\/\/\S+)/g, (match, i) => (
{match}
));
// Match @-mentions
replacedText = reactStringReplace(replacedText, /@(\w+)/g, (match, i) => (
@{match}
));
// Match hashtags
replacedText = reactStringReplace(replacedText, /#(\w+)/g, (match, i) => (
#{match}
));
// => [
// 'Hey ',
// @ian_sinn
// ', check out this link ',
// https://github.com/iansinnott/,
// '. Hope to see you at ',
// #reactconf,
// '',
// ];
```
### Full Example
See the [`example/`](https://github.com/iansinnott/react-string-replace/tree/master/example) directory for a runnable example.
## Why?
I wanted an easy way to do string replacement similar to `String.prototype.replace` within React components **without** breaking React's built in string escaping and XSS protection. This meant standard string replacement combined with `dangerouslySetInnerHTML` was out of the question.
## API
### reactStringReplace(string, match, replacementFunction, count)
#### string
Type: `string|array`
The string or array you would like to do replacement on.
**NOTE:** When passed an array this is the same as running the replacement on every string within the array. Any non-string values in the array will be left untouched.
#### match
Type: `regexp|string`
The string or RegExp you would like to replace within `string`.
**NOTE:** When using a `RegExp` you **MUST** include a capturing group. (`/(hey)/g` is ok, `/hey/g` is not.)
Example: Replace all occurrences of `'hey'` with `hey`
```js
reactStringReplace("hey hey you", /(hey)/g, () => hey);
```
#### replacementFunction
Type: `function`
The replacer function to run each time `match` is found. This function will be passed the matching string and an `index` which can be used for adding keys to replacement components if necessary. Character `offset` identifies the position of match start in the provided text.
```js
const replacementFunction = (match, index, offset) => {match};
reactStringReplace("hey hey you", /(hey)/g, replacementFunction);
```
#### count
Type: `number`
The number of substitutions to perform - for example if `count` is 1, then only the first occurrence of the string will be replaced.
Example: Replace first occurrence of `'hey'` with `hey`
```js
reactStringReplace("hey hey you", "hey", () => hey, 1);
```
## API Stability
The API is stable and production ready.
**v2.0.0 Breaking Change:** The `index` parameter passed to the replacement function now starts at 0 and increments by 1 (previously it started at 1 and incremented by 2).
For details on API tests see [the tests file](./index.test.js).
## License
MIT © [Ian Sinnott](https://github.com/iansinnott)