# string-replace-to-array

> Works like String.prototype.replace but outputs an array. Useful for replacing parts of the string with objects of other types.

Latest version **2.1.1** (published 2024-06-01) · MIT license · 0 weekly downloads

## Install

```sh
npm install string-replace-to-array
pnpm add string-replace-to-array
yarn add string-replace-to-array
bun add string-replace-to-array
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.1.1 |
| Published | 2024-06-01 |
| First published | 2016-04-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 12.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 24 |
| Author | Oz Michaeli |
| Maintainers | oztune |
| Keywords | string, replace, array, react, emoji |

## Links

- npm: https://www.npmjs.com/package/string-replace-to-array
- Repository: https://github.com/appfigures/string-replace-to-array
- Homepage: https://github.com/appfigures/string-replace-to-array#readme
- Issues: https://github.com/appfigures/string-replace-to-array/issues
- npm.io page: https://npm.io/package/string-replace-to-array

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 2.1.1 (latest) — 2024-06-01
- 2.1.0 — 2021-08-24
- 2.0.1 — 2021-08-18
- 2.0.0 — 2021-08-17
- 1.0.3 — 2017-06-05
- 1.0.2 — 2017-04-17
- 1.0.1 — 2016-04-28
- 1.0.0 — 2016-04-28

## README

# String replace to array

[![string-replace-to-array MIT license on NPM](https://img.shields.io/npm/l/string-replace-to-array.svg?style=flat-square)](https://www.npmjs.com/package/string-replace-to-array)
[![string-replace-to-array on NPM](https://img.shields.io/npm/v/string-replace-to-array.svg)](https://www.npmjs.com/package/string-replace-to-array)
[![Build Status](https://img.shields.io/circleci/project/appfigures/string-replace-to-array.svg)](https://circleci.com/gh/appfigures/string-replace-to-array)
[![string-replace-to-array total downloads on NPM](https://img.shields.io/npm/dt/string-replace-to-array.svg?style=flat-square)](https://www.npmjs.com/package/string-replace-to-array)
[![string-replace-to-array monthly downloads on NPM](https://img.shields.io/npm/dm/string-replace-to-array.svg?style=flat-square)](https://www.npmjs.com/package/string-replace-to-array)

Works just like `String.prototype.replace` but outputs an array instead of a string. It's [tiny](https://bundlephobia.com/package/string-replace-to-array) (<1KB) and has no dependencies.

## Why?

We built this for use with React, but it's very generic and doesn't depend on any environment. Consider the following scenario.

Given this string:

```
var content = 'Hello\nworld'
```

and this React markup:

```
<span>{ content }</span>
```

We'll get this output:
```
Hello world
```
_The newline character is ignored when the browser renders the resulting html._

The solution is to replace `\n` with `<br>`:

```
<span>{ replace(content, '\n', <br>) }</span>
```

and the output will be:

```
<span>Hello</br>world</span>
```
When rendered:
```
Hello
world
```

Now the newline will be rendered properly. Yay!

## Example usage

### Simple example

```
var replace = require('string-replace-to-array')
replace('Hello Amy', 'Amy', { name: 'Amy' })
// output: ['Hello ', { name: 'Amy' }]
```

### Full example

```
replace(
  'Hello Hermione Granger...',
  /(Hermione) (Granger)/g,
  function (fullName, firstName, lastName, offset, string) {
    return <Person firstName={ firstName } lastName={ lastName } />
  }
)

// output: ['Hello ', <Person firstName="Hermione" lastName="Granger" />, ...]
```

For a real-life example check out [react-easy-emoji](https://github.com/appfigures/react-easy-emoji), where this this is used to replace emoji unicode characters with `<img>` tags.

## Installation

```
npm install --save string-replace-to-array
```

## API

```
(string, regexp|substr, newValue|function) => array
```

The API mimics [String.prototype.replace](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace). The only differences are:

- The replacer (third parameter) doesn't have to be a string
- Returns an array instead of a string

## Inspiration

Mainly inspired by this conversation: https://github.com/facebook/react/issues/3386

### Why not use [react-replace-string](https://github.com/iansinnott/react-string-replace)?

Because we needed the full API of `String.replace`, especially the regex match parameters which get passed to the replace function.

---
_Source: https://npm.io/package/string-replace-to-array · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._