React Substitute

Highly configurable react substitute utility that can perform placeholder replacement by context values or react components.

Description

React substitute replaces placeholders in a string. Default placeholder format is {placeholder}
and can be changed in options by changing patter property. Placeholders can also contain
modifiers and local context, that can be handeled in transform function. Format of a modifier in placeholder is
{placeholder|modifier:context}. Modifier and context separators can be changed in options by changing modifierSeparator
property. If placeholder value is not matched with any key in context object, empty string is
returned, unless forceReplace is set to true. In that case, all placeholders will be processed and can be
replaced using custom logic in transform function.

Installation

``bash
yarn install @vojtechportes/react-substitute
`

or

`bash
npm install @vojtechportes/react-substitute
`

API

$3

1. str (string): String with placeholders to be replaced
2. options (object): Options object

#### Options

- pattern (RegExp): Placeholder pattern - defaults to {}

- modifierSeparator (string): Modifier separator - defaults to |

- contextSeparator (string): Local context separator - defaults to :

- context (unknown): Object containing structured json object containing values used to replace placeholders - defaults to {}

- forceReplace (boolean): If set to true, placeholders will be processed even if their values are not in context object - defaults to undefined

- transform (fn): Transform function with arguments value, placeholder, key, modifiers and context that returns string or number - defaults to undefined

- contextType ('list' | 'normal' | 'object'): Defines how context should be parsed. List will be split by commas, normal will be returned as is - defaults to normal

- returnReactElement (boolean): When true react element will be returned, otherwise string - defaults to false

- components (any[]): React components to be used for substitution: defaults to undefined

Examples

$3

`typescript
import { substitute } from '@vojtechportes/react-substitute';
import React, { PropsWithChildren } from 'react';

export interface ILinkProps {
to?: string;
}

export const Link: React.FC> = ({
children,
to,
}) => {children};

export default function App() {
const text =
'Lorem ipsum dolor sit amet {user|123, John Doe}, {user|456, Jane Doe}';

const substitutedText = substitute(text, {
transform: (value, _placeholder, key, _modifier, context) => {
if (key === 'user') {
const [userId, userName] = context;

return <0 to="/users/${userId}">${userName};
}

return value;
},
context: {
user: '',
},
contextSeparator: '|',
modifierSeparator: ':',
contextType: 'list',
components: [],
returnReactElement: true,
});

return

{substitutedText}

;

ReactDOM.render(, document.getElementById('root'));
}
`

$3

`typescript
import { substitute } from '@vojtechportes/react-substitute';
import React, { PropsWithChildren } from 'react';

export interface ILinkProps {
to?: string;
}

export const Link: React.FC> = ({
children,
to,
}) => {children};

export const FauxLink: React.FC> = ({
children,
}) => (
{children}
);

export default function App() {
const text =
'Lorem ipsum dolor sit amet {user|123, John Doe}, {user|456, Jane Doe} {token|789} {group|011} {group}';

const substitutedText = substitute(text, {
transform: (value, _placeholder, key, _modifier, context) => {
if (key === 'user') {
const [userId, userName] = context;

return <0 to="/users/${userId}">${userName};
}

if (key === 'token') {
const [tokenId] = context;

return <1>${key}: ${tokenId};
}

const [identifier] = context;

if (identifier) {
return <1>${identifier};
}

return value;
},
forceReplace: true,
contextSeparator: '|',
modifierSeparator: ':',
contextType: 'list',
components: [, ],
returnReactElement: true,
});

return

{substitutedText}

;
}

ReactDOM.render(, document.getElementById('root'));
}
``