Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

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: 3 months ago
JSON representation

A simple way to safely do string replacement with React components

Awesome Lists containing this project

README 

        
# React String Replace



[![react-string-replace.js on NPM](https://img.shields.io/npm/v/react-string-replace.svg)](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

yarn 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' ]



// Note that indexing [i] here starts at 1, not 0

// If you need to change this behavior for now try the workaround: 

let count = -1;

reactStringReplace("the more the better", "the", (match, i) => (

  count ++

  {match}

));

```



### 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



```js

import reactStringReplace from 'react-string-replace';



const HighlightNumbers = React.createClass({

  render() {

    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)



#### 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);

```



## API Stability



With v1.0.0 the API is considered stable and should be considered production ready. Pull requests are still welcome but there is currently no intent to make changes to this lib other than bug fixes (please submit an issue if you find something!).



For details on API tests see [the tests file](./test.js).



## License



MIT © [Ian Sinnott](https://github.com/iansinnott)