@doist/react-interpolate
v2.2.3
Published
A string interpolation component that formats and interpolates a template string in a safe way
Readme
react-interpolate
A string interpolation component that formats and interpolates a template string in a safe way.
import Interpolate from '@doist/react-interpolate'
function Greeting() {
return (
<Interpolate
string="<h1>Hello {name}. Here is <a>your order info</a></h1>"
mapping={{
name: 'William',
a: <a href="https://orderinfo.com" />,
}}
/>
)
}Would render the following HTML
<h1>Hello William. Here is <a href="https://orderinfo.com">your order info</a></h1>Component API
<Interpolate> component accepts the following props
string
The template string to be interpolated. Required.
Please see the 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.
<Interpolate
string="Hello {name}. Here is <orderLink>your order info</orderLink><hr/>. \
Please contact <supportLink>support</supportLink> for help"
mapping={{
// you can map placholder and self-closing tag to any valid element value
name: 'William',
hr: <hr className="break" />,
// you can map open & close tag to a rendering function
orderLink: (text) => <a href="https://orderinfo.com">{text}</a>,
// or you can map open & close tag to an element
supportLink: <a href="https://orderinfo.com" />,
}}
/>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.
// would render "an invalid string with unclose tag <h1>"
<Interpolate graceful string="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" section for more detail.
Interpolation syntax
Here is interpolation syntax you can use in your string.
Placeholder
'hello {user_name}'Placeholder name should be alphanumeric ([A-Za-z0-9_]). Placeholders could be mapped to any valid element value.
Open & close tags
'Here is <a>your order info</a>'
// tag name could be any alphanumeric string
'Here is <link>your order info</link>'
// you can nest tag and placeholder
'Here is <a><b>you order info {name}</b></a>'Tag name should be alphanumeric ([A-Za-z0-9_]).
Open & close tag could be mapped to an element value.
<Interpolate
string="Here is <a>your order info</a>"
mapping={{
a: <a href="https://orderinfo.com" />
}}
/>
// Invalid; the mapping value element should not contain children
<Interpolate
string="Here is <a>your order info</a>"
mapping={{
a: (
<a href="https://orderinfo.com">
<b />
<br />
</a>
)
}}
/>Open & close tag could be mapped to a rendering function, which would take a single argument that contains the enclosing text.
<Interpolate
string="Here is <a>your order info</a>"
mapping={{
a: (text) => (
<a href="https://orderinfo.com">
<b>{text}</b>
<br />
</a>
),
}}
/>Unclosed tag or incorrect nesting of tag would result in syntax error.
// bad: no close tag
'Here is <a>your order info'
// bad: incorrect tag structure
'Here is <a><b>your order info</a></b>'Self closing tag
'Hello.<br/>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.
// would render: <h1>Hellow</h1><br/>World
<Interpolate string="<h1>Hello</h1><br/>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 which has a slightly different placeholder syntax.
hello {{name}}You can define the formatting syntax of your string via syntax props.
import Interpolate, { TOKEN_PLACEHOLDER } from "react-interpolate"
const i18nNextSyntax = [
{
type: TOKEN_PLACEHOLDER,
regex: /{{\s*(\w+)\s*}}/g
}
]
// will output "hi steven"
<Interpolate
syntax={i18nNextSyntax}
string="hi {{name}}"
mapping={{
name: "steven"
}}
/>react-interpolate comes with i18next syntax support, and you can enable it via
import { SYNTAX_I18NEXT } from "react-interpolate"
<Interpolate
syntax={SYNTAX_I18NEXT}
...
/>Releasing
Releases are fully automated with semantic-release. There is no manual version bump: the next version number, the changelog, the git tag, the GitHub release, and the npm/GitHub Package Registry publishes are all derived from the commit history.
Every push to main runs the Release workflow, which:
- analyses the Conventional Commits since the last release to determine the next version (
fix:→ patch,feat:→ minor,feat!:/BREAKING CHANGE→ major), - updates
CHANGELOG.md,package.json, andpackage-lock.jsonand commits them back, - tags the release and publishes the GitHub release notes, and
- publishes the package to npm with provenance.
Because the version is inferred from commits, pull request titles and commits must follow the Conventional Commits format — this is enforced by the Semantic Pull Request check. If a batch of commits contains no releasable changes (e.g. only chore:/docs:/ci:), no release is published.
Pushes to the next branch publish a prerelease on the next dist-tag without updating the changelog.
