https://github.com/doist/react-interpolate
A string interpolation component that formats and interpolates a template string in a safe way.
https://github.com/doist/react-interpolate
Last synced: 5 months ago
JSON representation
A string interpolation component that formats and interpolates a template string in a safe way.
- Host: GitHub
- URL: https://github.com/doist/react-interpolate
- Owner: Doist
- License: mit
- Created: 2020-04-03T09:50:20.000Z (over 6 years ago)
- Default Branch: main
- Last Pushed: 2025-02-18T12:26:14.000Z (over 1 year ago)
- Last Synced: 2025-06-28T05:48:06.859Z (about 1 year ago)
- Language: JavaScript
- Homepage:
- Size: 1.44 MB
- Stars: 16
- Watchers: 10
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# react-interpolate
[](http://img.badgesize.io/https://cdn.jsdelivr.net/gh/Doist/react-interpolate/dist/react-interpolate.min.cjs?compression=gzip) [](https://github.com/Doist/react-interpolate/actions)
A string interpolation component that formats and interpolates a template string in a safe way.
```jsx
import Interpolate from '@doist/react-interpolate'
function Greeting() {
return (
,
}}
/>
)
}
```
Would render the following HTML
```html
Hello William. Here is your order info
```
## Component API
`` component accepts the following props
#### `string`
The template string to be interpolated. Required.
Please see the [Interpolation syntax](./#interpolation-syntax) section below for more detail.
#### `mapping`
An object that defines the values to be injected for placeholder and tags defined in the template string. Optional.
- For placeholder or self-closing tag, the mapping value could be any valid element value
- For open & close tag, the mapping value could be either renderer function or an element.
```jsx
,
// you can map open & close tag to a rendering function
orderLink: (text) => {text},
// or you can map open & close tag to an element
supportLink: ,
}}
/>
```
#### `graceful`
A boolean flag indicates how string syntax error or mapping error should be handled. When true, the raw string value from the prop `string` would be rendered as a fallback in the error scenario. When false, error would be thrown instead.
Optional. `true` by default.
```jsx
// would render "an invalid string with unclose tag <h1>"
```
#### `syntax`
Optional. `syntax` props allow use of react-Interpolate with different string formatting syntax. Please see the ["Custom syntax support"](#custom-syntax-support) section for more detail.
## Interpolation syntax
Here is interpolation syntax you can use in your `string`.
#### Placeholder
```jsx
'hello {user_name}'
```
Placeholder name should be alphanumeric (`[A-Za-z0-9_]`). Placeholders could be mapped to any valid element value.
#### Open & close tags
```jsx
'Here is your order info'
// tag name could be any alphanumeric string
'Here is your order info'
// you can nest tag and placeholder
'Here is you order info {name}'
```
Tag name should be alphanumeric (`[A-Za-z0-9_]`).
Open & close tag could be mapped to an element value.
```jsx
}}
/>
// Invalid; the mapping value element should not contain children
)
}}
/>
```
Open & close tag could be mapped to a rendering function, which would take a single argument that contains the enclosing text.
```jsx
(
{text}
),
}}
/>
```
Unclosed tag or incorrect nesting of tag would result in syntax error.
```js
// bad: no close tag
'Here is your order info'
// bad: incorrect tag structure
'Here is your order info'
```
#### Self closing tag
```js
'Hello.
Here is your order'
```
Tag name should be alphanumeric (`[A-Za-z0-9_]`). Self closing tags could be mapped to any valid element value.
## Auto tag element creation
When tags are used the string but there are no correponding mapped value, it would by default create the corresponding HTML element by default.
```jsx
// would render:
Hellow
World
```
## Custom syntax support
You may already be using a formatting syntax in your string that is different than the built-in syntax support from Interpolate. You can configure Interpolate so that it could recognize the formatting syntax that you use.
For instance, you may be using [i18next](https://www.i18next.com/) which has a slightly different placeholder syntax.
```
hello {{name}}
```
You can define the formatting syntax of your string via `syntax` props.
```jsx
import Interpolate, { TOKEN_PLACEHOLDER } from "react-interpolate"
const i18nNextSyntax = [
{
type: TOKEN_PLACEHOLDER,
regex: /{{\s*(\w+)\s*}}/g
}
]
// will output "hi steven"
```
react-interpolate comes with i18next syntax support, and you can enable it via
```jsx
import { SYNTAX_I18NEXT } from "react-interpolate"
```
# Releasing
A new version of @doist/react-interpolate is published both on npm and GitHub Package Registry whenever a new release on GitHub is created.
To update the version in both `package.json` and `package-lock.json` run:
```sh
npm --no-git-tag-version version
```
Once these changes have been pushed and merged, create a release on GitHub.
A GitHub Action will automatically perform all the necessary steps and will release the version number that's specified inside the `package.json`'s `version` field so make sure that the release tag reflects the version you want to publish.