https://github.com/aduth/terpolate
String interpolation for React, Preact, and plain DOM
https://github.com/aduth/terpolate
i18n preact react
Last synced: 28 days ago
JSON representation
String interpolation for React, Preact, and plain DOM
- Host: GitHub
- URL: https://github.com/aduth/terpolate
- Owner: aduth
- License: mit
- Created: 2021-07-17T20:19:07.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2021-10-02T16:47:57.000Z (over 4 years ago)
- Last Synced: 2025-04-05T08:14:29.752Z (about 1 year ago)
- Topics: i18n, preact, react
- Language: JavaScript
- Homepage:
- Size: 309 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Terpolate
String interpolation for React, Preact, and plain DOM.
Why use Terpolate?
- 🔬 **Small**: 0.3kb gzipped before factoring in React or Preact, or 0.5kb for the standalone DOM package.
- 🔒 **Safe**: Builds an element tree using only string content, never dangerous HTML.
- 📟 **Compatible:** Still supports outdated browsers such as Internet Explorer.
What are some use-cases?
- 🌍 Internationalization (i18n)
- 🧼 Simple HTML sanitization
## Installation
Install via NPM:
```
npm install terpolate
```
## Usage
### React
The package exports a single function, `interpolate`:
```js
import { interpolate } from 'terpolate';
```
The function accepts two arguments:
1. A string with markup to replace
2. An object with markup tag component implementations
The return value is an element which can be included in the rendered value of your component.
For example:
```js
function Blink({ children }) {
return {children};
}
function Message() {
const interpolated = interpolate('Hello world', { Blink });
// ⇒ ['Hello ', world]
return
{interpolated};
}
```
Handlers can be given as a string, component class or function, or as an element. When given as an element, the element is cloned with text inserted as children.
```js
interpolate(
'If you need help, visit our Help Center.',
{
strong: 'strong',
HelpCenterIcon,
a: ,
}
);
```
### Preact
All of the above still applies, but you should import from `terpolate/preact` instead:
```js
import { interpolate } from 'terpolate/preact';
```
### DOM
Similarly, import from `terpolate/dom`:
```js
import { interpolate } from 'terpolate/dom';
```
The return value is a [`DocumentFragment`](https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment) which you can then append to a container:
```js
const link = document.createElement('a');
link.href = '/help';
const element = interpolate(
'If you need help, visit our Help Center.',
{
strong: 'strong',
a: link,
}
);
document.body.appendChild(element);
```
Note that the DOM entrypoint assumes a DOM is present, meaning it should be run either in a browser or in a Node.js environment with DOM globals using a module like [`jsdom-global`](https://www.npmjs.com/package/jsdom-global).
## License
Copyright 2021 Andrew Duthie
Released under the [MIT License](./LICENSE.md).